Maintaining this documentation

This site is generated from the docs/ directory of this repository with Antora + AsciiDoc. There is no separate documentation repository, no CI and no hosted publishing step: the site is built locally from a git tag of this repo.

Directory layout

playbook.yml                    # Antora playbook (repo root)
package.json                    # pinned build tooling (antora, lunr search extension)
docs/
  antora.yml                    # component name + version
  ui/                           # vendored UI (official default UI + Mermaid)
  modules/ROOT/
    nav.adoc                    # the left-hand navigation (one entry per page)
    pages/                      # one .adoc file per page
    images/                     # page images (screenshots, banner)
  ralph-*.png, screenshots/     # originals also served by the dashboard (/docs/*)
build/site/                   # build output (regenerated, not committed)

The original screenshots in docs/ stay in place because the live dashboard serves them at /docs/* (Dashboard HTTP API). The copies under docs/modules/ROOT/images/ are the ones this site uses.

Build and preview

# 1. the version comes from a git tag: tag the commit the docs describe
git tag v1.0.0                  # already done for this release

# 2. install the build tooling (antora + search extension; node_modules is git-ignored)
npm install

# 3. build (Node 18+ required)
npx antora playbook.yml

# 4. preview
open build/site/ralph-orchestrator/1.0.0/index.html
# or serve it:
python3 -m http.server 8080 -d build/site
# -> http://127.0.0.1:8080/ralph-orchestrator/1.0.0/

build/ is regenerated on every build and is excluded from version control (.gitignore).

Publishing to GitHub Pages (optional)

GitHub Pages requires a public repository, so this is not used while the repo stays private. If it ever becomes public, the site is served at https://tefiros.github.io/ralph-orchestrator/ from a static gh-pages branch (a current build is already pushed there). There is no CI: the build stays local, and the branch only carries the generated HTML.

# after rebuilding the site (steps above):
SCRATCH=$(mktemp -d)
rsync -a build/site/ "$SCRATCH/"
touch "$SCRATCH/.nojekyll"                # required - see below
cd "$SCRATCH"
git init -q
git add -A && git commit -m "Docs site build"
git remote add origin git@github.com:tefiros/ralph-orchestrator.git
git push -f origin HEAD:gh-pages          # force: the branch is generated output, no history
cd - && rm -rf "$SCRATCH"

  • Build the branch outside the main worktree. Doing the orphan-branch dance in the repo deletes .gitignore from the worktree (git rm -rf .), so the next git add -A sweeps node_modules/ and build/ into the branch — and checking back out to main then deletes both directories from the worktree. A scratch clone (as above) cannot touch the main worktree.

  • .nojekyll is mandatory: without it GitHub’s Jekyll step deletes the _ folder and the site loses all CSS and JS.

  • First publication only: enable Pages in the repository settings (Settings → Pages → Deploy from a branch → gh-pages / root).

  • Every docs change means: commit, git tag -f v1.0.0, rebuild, sync gh-pages, push.

Versioning

  • The documentation version is a git tag of this repository. The current tag is v1.0.0, which maps to the application version 1.0.0 declared in pyproject.toml (Ralph Orchestrator).

  • To document a new release: update the pages, commit, move the tag (git tag -f v1.0.0 while it is still local, or add the next tag and list it in playbook.yml under content.sources[0].tags), rebuild.

  • The Antora generator version is pinned in package.json (devDependencies.antora) — pin it deliberately and keep the pinned version working.

Adding or changing content

  • New page — create docs/modules/ROOT/pages/<name>.adoc and add a line to docs/modules/ROOT/nav.adoc (indent under its parent for grouping). A page that is not in nav.adoc still builds, but it is unreachable from the navigation.

  • Cross-references — use xref:other-page.adoc[link text] (same module) so Antora resolves and validates them at build time.

  • Images — put the file in docs/modules/ROOT/images/ and reference it as image::name.png[caption].

  • Diagrams — Mermaid diagrams are rendered client-side by the UI. Wrap the diagram source in a Mermaid div inside a passthrough block:

    [source,asciidoc]
....
++++
<div class="mermaid">
flowchart LR
    A --> B
</div>
++++
....
    The UI loads `js/vendor/mermaid.min.js` (vendored under `docs/ui/`) and renders every
`.mermaid` element on page load.

Accuracy rules

  1. The source code is authoritative. Every component name, flag, endpoint, default value and behavior described here must match ralph_orchestrator/*.py, config.yaml, install.sh, mockup/ or the tests. When you change code, change the page in the same commit.

  2. Do not document intended or future behavior.

  3. Keep secrets out: the shipped config.yaml has empty credential placeholders (Configuration reference).

  4. Verify before you claim: run the commands you paste (orch.py check, pytest -q, the showcase) when you change what they are expected to do (Verification and tests).