Aegis documentation

#Writing documentation

The manual is Markdown in docs/, rendered into a static site by the panel's own builder. No third-party generator, no network access, no npm: the same Python that runs the platform renders the pages.

bash
aegis docs build                 # docs/ → public/docsaegis docs build --out /tmp/siteaegis docs web                   # build, then serve on a free port

The builder reports how many pages it wrote and prints the entry point.

#Adding a page

  • Create docs/<name>.md. Start with a single # Title — it becomes the page
  • title and the browser tab.

  • Add it to the sidebar in app/modules/docs/pages.py: a `Page(source, title,
  • href)` inside the section it belongs to.

  • Add a row to the table in docs/README.md.
  • aegis docs build.
  • A file that is missing from the sidebar is not lost: it is appended under an "Other" section, in file order. That is a safety net, not an arrangement — write the order by hand, because that is what a reader follows.

    #What the parser understands

    The subset GitHub also renders, and nothing beyond it:

  • # … ###### headings; ## and ### also build the table of contents;
  • fenced code blocks with a language (``bash, `ini, ``json get syntax
  • highlighting);

  • tables with a header row and a --- separator;
  • bullet and numbered lists, nested by indentation;
  • blockquotes (>), horizontal rules (---);
  • inline ` code , bold, italic and links`.
  • Anything else stays a paragraph — the parser fails safe instead of guessing.

    Write links as if you were on GitHub: [tasker](tasker.md). The builder rewrites every *.md target to the generated .html page, so the same text works in the repository and on the site. External URLs are left alone.

    Anchors come from the headings (## Live feed → #live-feed), so a link to a section is live.md#live-feed.

    #Style

  • English, like the code and the commit messages.
  • One # per page. Short sections; a table for anything with more than two
  • columns; a code block for anything an operator types.

  • Explain why, not only what. A page that only lists keys is a reference, and
  • a reference that never says which value to choose is not much help.

  • Current behaviour only. A page describing an older release is worse than no
  • page: it teaches something false with confidence.

  • Keep examples runnable: real paths (/aegis/data/www), real commands, the
  • output shape the panel actually returns.

    #Where each topic lives

    TopicPage
    installation, architecture, configurationtop level
    command line, keeper, tasker, permissions, live feedOperations section
    one application and its cubecubes/<name>.md
    the panel and its JSON APIpanel.md, api.md
    panel internals (routes, templates, components)panel-development.md
    errors already mettroubleshooting.md
    what is nextroadmap.md

    #Files

    PathContent
    docs/the sources, one file per page
    app/modules/docs/pages.pysidebar order and section names
    app/modules/docs/markdown.pythe parser
    app/modules/docs/highlight.pythe shell/ini/json highlighter
    app/modules/docs/theme.py, script.pystylesheet and script served with the site
    public/docs/generated output; rebuild it, do not edit it

    The builder writes every page and never deletes: a document removed from docs/ leaves its generated HTML behind until the output directory is cleaned. Treat public/docs as disposable output, never as the source.