Aegis documentation

#docs

The manual is Markdown in docs/, and the platform renders it with its own builder — no third-party generator, no network access, no npm. aegis docs builds that site to HTML and, when you want it, serves it locally so a change to a page is one command away.

There are two actions: build writes the site, web writes it and serves it. Nothing here touches a running service; the panel only serves what build leaves in public/docs.

#aegis docs

bash
aegis docs <action> options
ActionPurpose
buildgenerate the static site
webbuild, then serve it until interrupted

aegis docs without an action is a usage error and exits 2; aegis docs --help lists the actions.

#aegis docs build

Renders every Markdown document under docs/ into HTML, writes the shared stylesheet and script, and builds The CLI Book as its own site under <out>/cli-book/. It overwrites the files it writes and deletes nothing.

#Syntax

bash
aegis docs build --out DIR

#Options

OptionDefaultEffect
--out DIRpublic/docsoutput directory, created when missing

The default is relative to the project root, because the launcher changes there before running the command.

#What gets written

PathContent
<out>/index.htmlthe landing page, rendered from docs/README.md
<out>/<page>.htmlone page per document, at its relative path
<out>/cubes/<cube>.htmlthe per-cube pages
<out>/cli-book/index.htmlthe landing page of The CLI Book
<out>/cli-book/*.htmlone page per book document
<out>/assets/site.cssthe stylesheet every page links
<out>/assets/site.jsthe script every page links
<out>/cli-book/assets/the book's own copy of both, so it stands alone
  • The sidebar and its section names for the manual come from
  • app/modules/docs/pages.py. A document on disk that is not listed there is appended under "Other", so a new page is never silently dropped.

  • The book's sidebar comes from app/modules/docs/book.py. A file under
  • docs/cli-book/ that is not listed there is not part of the book site, but the main build still writes it under "Other".

  • A page whose source file is missing is skipped, not rendered empty. If
  • docs/cli-book/ itself is absent, the book step is skipped and the count covers the manual only.

  • README.md is written twice: as README.html and as index.html.
  • Only Markdown is rendered: other files in docs/ (images, data) are not
  • copied to the output.

  • Nothing is deleted: a document you remove leaves its old HTML behind until
  • the output directory is cleaned. Treat public/docs as disposable output, never as a source.

  • The panel serves public/docs at /docs/, so the book is at
  • /docs/cli-book/ there. It only serves what build has written.

    #Examples

    bash
    aegis docs build

    Every page of the manual and of the book into public/docs.

    bash
    aegis docs build --out /tmp/aegis-docs

    A throwaway copy, for checking a page without touching the one the panel serves.

    #Output

    text
    ✔ 85 pages written to public/docsℹ open public/docs/index.html

    The first number is the pages written in that run: the manual plus the book. It changes whenever a document is added, so treat it as a sanity check rather than a constant. It counts pages written, not distinct files — the book lives under docs/cli-book/, so the main build discovers its documents too and writes them once before the book build writes them again with the book's sidebar.

    The second line prints the entry point of the generated site, using the --out value as given.

    There is no per-page report. A directory it cannot create, or a file it cannot write, ends the run with the operating system's error and a non-zero exit; a page that is missing is simply skipped.

    #aegis docs web

    Builds the same site, then serves the output directory over HTTP until you stop it. This is a preview server: static files, plain HTTP, no authentication and no TLS.

    #Syntax

    bash
    aegis docs web --host HOST --port PORT --out DIR

    #Options

    OptionDefaultEffect
    --host HOST0.0.0.0interface to bind
    --port PORT0TCP port; 0 lets the operating system pick a free one
    --out DIRpublic/docsoutput directory; the same tree is served

    #Examples

    bash
    aegis docs web

    Build, then listen on every interface on a free port — the quickest way to read the site from another machine on the same network.

    bash
    aegis docs web --host 127.0.0.1 --port 8080

    Loopback only, on a port you chose. Open http://127.0.0.1:8080/ for the manual and http://127.0.0.1:8080/cli-book/ for the book.

    #Output

    text
    ✔ 62 pages on http://0.0.0.0:41273/⚠ listening on every interface; press Ctrl+C to stop
    text
    ✔ 62 pages on http://127.0.0.1:8080/

    The success line carries the address and the port actually used, which is how you learn the free port chosen for --port 0. It counts the pages of the manual; the book is served next to them at /cli-book/ and is not included in that number. The warning appears only when the host is 0.0.0.0.

    Press Ctrl+C to stop:

    text
    ℹ stopped

    #Notes

  • The handler reads from disk on every request, so running aegis docs build
  • in another shell updates what the browser receives. Reload the page.

  • Ctrl+C stops the server, prints stopped and exits 0. This is the exception
  • to the 130 convention: the command owns the interrupt.

  • 0.0.0.0 exposes the manual to every network the host is on. There is no
  • password, so bind 127.0.0.1 unless the network is trusted.

  • If the address or port cannot be bound, the operating system's error ends the
  • command with a non-zero exit; the site is already built at that point.

  • The build step runs before the server starts. If the build fails, nothing is
  • served.

    #Exit codes

    CodeMeaning
    0the site was built and the server ran until Ctrl+C stopped it
    non-zerothe build failed, or the address and port could not be bound

    See Writing documentation for the Markdown subset the builder accepts and where a new page has to be registered, and Conventions for the global options and the exit codes used across the whole CLI.