cla docs - Help and Documentation Generation

cla docs: Exports the help docs into a Mkdocs static site, one folder per language.

Note: For this command to work, you need to install Mkdocs, which in turn requires Python.

Site layout

Each language is exported into its own folder under the site root:

root/static/mkdocs/
    index.html      <- sends the browser to its own language
    en/
    es/

The prefix is not cosmetic. The documentation theme rewrites every absolute link and image to start with the language it was built for, and the language selector in the header swaps that same prefix. A site without the folders cannot resolve either, and every page answers with a 404.

Running cla docs with no options exports every language found under docs/, so the language selector always has somewhere to go. The site root is emptied first.

Publishing the site

To publish the documentation on a web server, copy the contents of each language folder into the folder of the same name in the web root, and the root index.html into the web root itself:

cla docs --doc-langs en,es
cp -r root/static/mkdocs/en/. /path/to/webroot/en/
cp -r root/static/mkdocs/es/. /path/to/webroot/es/
cp root/static/mkdocs/index.html /path/to/webroot/

Do not copy the whole site root into a language folder (cp -r root/static/mkdocs/* /path/to/webroot/en/). That nests en/en/ and replaces en/index.html with the root index.html, which only redirects to a language, so /en/ keeps redirecting to itself.

Serving the site locally

cla docs-serve

cla docs-serve exports the site first and then serves it, so what you read is always what is on disk. Pass --no-rebuild to skip the export and serve the last build, which is what you want when you are only looking around.

It takes port 5555, or a free port picked by the operating system when something else already holds it. It resolves folder URLs to their index.html, so the pretty links Mkdocs writes work the same as they do in production, and it closes the listening socket on Ctrl-C so the port is free immediately afterwards.

Options:

--doc-lang en|es

Export a single language instead of all of them. The site root still keeps the per-language folder, so --doc-lang es produces es/ and nothing else.

Defaults to the language of your shell.

--doc-langs en,es

Export a specific list of languages. Takes precedence over --doc-lang.

--mkdocs-path dir

The path to the folder where the temporary Mkdocs site will be created.

Warning: everytime this command executes, the mkdocs folder is completely deleted before being written to.

--site-dir dir

The final destination site.

If no dir is specified, the documentation static site will be created under /static/mkdocs in your Clarive server.

--no-rebuild

Serve the existing build instead of exporting first. Fails if there is nothing built yet.

--serve-port 5555

The port cla docs-serve listens on. Without it, 5555 is used when free and a random free port otherwise.

--serve-host 127.0.0.1

The address cla docs-serve binds to. Pass 0.0.0.0 to reach the site from another machine.