Makes the documentation searchable from <mmo-app>'s command palette, the one search box of the application: the search endpoint (SearchController::routeSearch) is declared in MMO.config.searches, and the palette lists what it answers under its own heading, next to the pages and the commands.
function addSearchSource(MMO\core\documents\Document $document, ?string $page = null): void
Namespace
MMO\doc
The first call wins: [`DocPageController`](https://mmoframework.fr/en/documentation/mmo.doc/php/controllers/DocPageController.md#docpagecontroller) calls it first with the page the reader is on, so what is
documented on that page comes first; the listener every html page goes through only adds it when missing.
The canonical in-page anchor for a symbol or member name.
function anchor(string $name): string
Namespace
MMO\doc
Every renderer goes through this one function, so a link built by [`MarkdownPrinter`](https://mmoframework.fr/en/documentation/mmo.doc/php/MarkdownPrinter.md#markdownprinter)
and one built by [`DocPageController`](https://mmoframework.fr/en/documentation/mmo.doc/php/controllers/DocPageController.md#docpagecontroller) always agree: lowercased, namespace/path
separators and sigils dropped, anything else that is not a letter, a digit or a `-` folded into a `-`.
Build the code documentation of $names with mmo.doc, into each library's own documentation folder: docs/php/ from the reflection of its loaded php, docs/js/ from its parsed javascript and .jhs -- a .md page and its .doc.json model per file, and an index.json. Every library's git ignores them; a phar carries them (PackageManifest::build takes its documentation folders whole).
function buildDocumentation(?array $names = null, ?callable $log = null): bool
Namespace
MMO\doc
What an earlier run generated is removed first: the generators never remove a page, and the index keeps every
symbol it ever saw, so a class deleted since would still be documented. Only what git ignores in those folders
is removed -- a file a library commits there is left alone -- and nothing is removed unless everything can be.
The libraries must be loaded (the php generator documents what reflection sees), so this runs in a script that
loaded the project, not in a request. `{bin}` is moved to a temporary folder: Documentor wires itself into
mmo.client when it is built, which would write prism.js and mmo.doc.css into the project's own.
false when a generator failed: what it was building is incomplete
throws
when a name is not a library the project packages
throws
when an earlier run's files cannot be replaced (they belong to another user, the web server's through mmo.doc's control panel): nothing was removed, and the message says how to give them back
Compiles src/styles/documentation.scs to {bin}/mmo.doc.css, recompiling only when the source is newer (dev mode only -- like MMO\client\Theme's own asset jobs, a production deploy is expected to build this ahead of time).
function compileDocumentationCss(): ?string
Namespace
MMO\doc
It is Simple CSS, compiled by [`SCSCompiler`](https://mmoframework.fr/en/documentation/mmo.client/php/SCSCompiler.md#scscompiler) with `emitThemes` off: the design tokens are
already declared on `:root` by the app's own `mmo.client.css`, and this stylesheet only *references* them,
so a theme switch reaches the documentation pages like any other page.
Serve the documentation to readers, and nothing else: for a public site (www.mmoframework.fr) rather than a developer's checkout. documentation is the index of everything documented, documentation/mmo.core/php/server/Route.md a page of it, under a bar searching every symbol (doc/search).
function connectReadOnly(): void
Namespace
MMO\doc
Only what reads: the page tree, its renderer and the search. Call it INSTEAD of [`Documentor::Shared()`](https://mmoframework.fr/en/documentation/mmo.core/php/classes/aModule.md#amodule-shared),
which also connects the control panel (`tools/mmo/doc`: anyone could regenerate the documentation) and the
example runner (`doc/example/run`, which runs code), and puts the panel in the menu. Needs mmo.client.
The menu lists the documentation and its libraries, not the thousand pages under them, which every page of the
site would carry: they stay reachable from the index, the search and a library's page. A scaffolding template
(`{{name}}`) documents no library and is hidden.
Like [`connectToClient()`](https://mmoframework.fr/en/documentation/mmo.doc/php.md#connecttoclient), call it once, before the first request is routed.
Copies mmo.client's vendored vendor/prism/prism.js (a Prism.js build already bundling the markup/js/scss/ css/markdown/php grammars) out to {bin}/prism.js, so it's actually servable -- Theme's own asset pipeline never picks up files under a package's vendor/ folder. Only copies when missing/stale.
what an earlier run generated in $folder, a library's documentation folder: php/, js/ and their php.md/js.md summaries, and only the files the library's git ignores (none when it is no checkout)
Replace every @see reference of a markdown text with a link to its target, or with inline code when the target is documented nowhere. Fenced code blocks are left alone.
function linkSees(string $text, array $sees, callable $href): string
what of an earlier run in $folder cannot be replaced: a file, or a folder whose entries cannot be removed. Written by another user -- the web server, through mmo.doc's control panel (tools/mmo/doc).
Every target the @see references of a text point at, cleaned of the punctuation the sentence around it glued on (@see stop., (stop)), and split when several are written as one (@see getFilename/getUrl).