Writing these docs

docs/ is an Antora documentation component, not a standalone site. It has no playbook of its own: the central documentation project, Payability/pyb-technical-docs, consumes it as a content source and builds it with the other components.

Consuming this component

Add the repository to the central playbook’s content sources:

content:
  sources:
    - url: https://github.com/Payability/EventLoggerApp.git
      branches: new-rules-P312
      start_path: docs

start_path: docs is what makes Antora find docs/antora.yml. Add the component to the hub’s navigation and start page with EventLogger Rules.

Component descriptor

Key Value

Key	Value
`name`	`eventlogger-rules`, used in every cross-component xref
`title`	`EventLogger Rules`, shown in the component selector
`version`	`~`: unversioned, so URLs have no version segment
`start_page`	`ROOT:index.adoc`
`nav`	One entry per module navigation file, in menu order
`asciidoc.attributes`	Shared facts (accounts, stacks, branches, secret name), written once

name

eventlogger-rules, used in every cross-component xref

title

EventLogger Rules, shown in the component selector

version

~: unversioned, so URLs have no version segment

start_page

ROOT:index.adoc

nav

One entry per module navigation file, in menu order

asciidoc.attributes

Shared facts (accounts, stacks, branches, secret name), written once

Referencing this component from another one:

xref:eventlogger-rules::architecture.adoc[EventLogger Rules architecture]
xref:eventlogger-rules:operations:cutover.adoc[Cutover runbook]

Modules

Module Scope

Module	Scope
`ROOT`	The application: architecture, event processing, API, configuration, development, deployment, security
`operations`	Runbooks: monitoring, the Zappa to SAM cutover, rollback, decommissioning

ROOT

The application: architecture, event processing, API, configuration, development, deployment, security

operations

Runbooks: monitoring, the Zappa to SAM cutover, rollback, decommissioning

Authoring rules

One topic per page; start each page with a title and a :description:.
Use the attributes from antora.yml (625663093496, eventlogger-rules-prod, …) in prose instead of repeating values. Attributes are not substituted inside source blocks, so commands there spell values out.
Write diagrams as Mermaid in a source block. The hub renders [source,mermaid] blocks; a [mermaid] literal block is shown as plain text.
```
[source,mermaid]
----
flowchart LR
  A --> B
----
```
Images go in modules/<module>/images/, files included verbatim in modules/<module>/examples/.
examples/make-help.txt is generated: run make docs-help after changing Makefile targets.
Link between pages with xref:, never with URLs to the built site.