Writing these docs

docs/ is an Antora documentation component, not a site. The central Payability documentation site (the pyb-docs repository) lists it as a content source:

content:
  sources:
    - url: https://github.com/Payability/ActionsToolsApp.git
      branches: [release]
      start_path: docs

docs/antora.yml declares the component actionstools-app, unversioned (version: ~), so the site shows the state of release. Pages elsewhere link here with xref:actionstools-app::index.adoc[].

Attributes under asciidoc.attributes ({project-name}, {repo-url}, {repo-tree}, {python-version}, {prod-env}, {dev-aws-account}, {prod-aws-account}, {prod-stack}, {stage-stack}, {prod-url}) are soft-set with @; use them instead of repeating values.

Layout

docs/
├── antora.yml
└── modules/ROOT/
    ├── nav.adoc          every page must be listed here
    ├── pages/            index, architecture, request-lifecycle, api/, async/, data/,
    │                     components/, operations/, contributing/, reference/
    └── examples/         JSON payloads, included as example$<name>.json

Conventions

  • One page, one subject, with a level-0 title, :navtitle: and a one-sentence :description:.

  • Cross-references use xref:<path in pages>[]; anchors are generated with idprefix: '' and idseparator: '-', so == Smoke test after a deploy is #smoke-test-after-a-deploy.

  • Source paths are monospace (tasks/services.py), not links.

  • Payloads live in examples/ and are included, never pasted twice.

  • Tables get options="header" and explicit cols=; escape a literal | as \|.

  • Admonitions: NOTE for context, IMPORTANT for a contract, WARNING for a foot-gun.

  • No secrets — not even expired ones. Use placeholders like <token>.

Previewing locally

# /tmp/local-playbook.yml
site:
  title: actionstools-app (local)
  start_page: actionstools-app::index.adoc
content:
  sources:
    - url: .            # run from the repository root
      branches: HEAD
      start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
npx antora --fetch /tmp/local-playbook.yml && open build/site/index.html

Antora reads committed content from git: commit (or use a worktree) before previewing.

Keeping the docs truthful

Updating the page is part of the change:

Change Page

A new or changed route

API overview route catalog and the resource page

A new async task or Worker event

Worker Lambda & async tasks

Counter behaviour

Task counters

A new table, index or attribute

DynamoDB tables

A new downstream service

a page under Integrations

A new setting or secret

Configuration & secrets, Settings & secrets reference

template.yaml, samconfig.toml, CI

System architecture, Deployment

A new failure mode

Troubleshooting

A new file worth finding

Source map