Docs Maintenance

This project should treat repository documentation as the canonical source and Confluence as a publishing target.

Authoring Model

Write and review documentation in Markdown inside this repository:

  • project overview and onboarding
  • install and developer setup
  • deployment instructions
  • CLI reference
  • operational runbooks

This keeps documentation versioned with the code it describes.

Updating CLI Reference

Do not manually edit the generated help blocks in the CLI pages. Refresh them with:

python3 scripts/generate_cli_docs.py

If the parser behavior changes in deploy/args.py, deploy/slservice_cli.py, or deploy/sladmin_cli.py, regenerate the pages in the same change set.

Publishing To Confluence

For Confluence, the simplest maintainable path is:

  1. Keep the source in Markdown here.
  2. Convert the pages you want to publish to .docx.
  3. Import the .docx files into Confluence.

If you use Pandoc locally, a typical conversion looks like:

pandoc docs/deployment.md -o deployment.docx

For larger publications, you can also build the docs site locally with MkDocs:

mkdocs serve
mkdocs build

Running The Docs Container

The repository root includes a Dockerfile for hosting this MkDocs site. Build the image from the repository root:

docker build -t gen5-deploy-docs .

If the image will run on ECS EC2, build it for linux/amd64 so it matches the runtime instances. This avoids exec format error failures when the image is built on an ARM workstation:

docker buildx build --platform linux/amd64 -t gen5-deploy-docs .

Run the container and publish MkDocs on local port 3000:

docker run --rm -p 3000:3000 gen5-deploy-docs

Then open:

http://localhost:3000

The container runs mkdocs serve --dev-addr=0.0.0.0:3000, so it binds inside Docker instead of only on localhost.

Publishing To ECR

The remote image repository is:

838694328347.dkr.ecr.us-east-1.amazonaws.com/ops-docs

Authenticate Docker to ECR with the prod AWS profile:

aws ecr get-login-password --profile prod --region us-east-1 | docker login --username AWS --password-stdin 838694328347.dkr.ecr.us-east-1.amazonaws.com

Tag the local linux/amd64 image for the remote repository:

docker tag gen5-deploy-docs:latest 838694328347.dkr.ecr.us-east-1.amazonaws.com/ops-docs:latest

Push the image:

docker push 838694328347.dkr.ecr.us-east-1.amazonaws.com/ops-docs:latest

Suggested Maintenance Rule

Any code change that adds, removes, or changes:

  • a deployment step
  • an environment prerequisite
  • a command-line flag
  • an operational workflow

should include the corresponding docs change in the same pull request.