Docs init

Sets up documentation as code in the repository the user is working in. Pages are Markdown files in docs/<space>/. scripts/build_docs.py turns them into a static site with a health page that lists pages without an owner and pages past their review date.

Inputs

• The repository: the current working directory, or a path the user names.
• The spaces. A space is one section of the docs with its own home page. For each: key (folder name, a-z, 0-9 and -), name, about (one sentence) and owner (a person or a team).
• Optional: the output folder (default site/docs), the URL prefix (default /docs/) and the base URL for canonical links (default none).

Steps

1. Check the repository. Find the root with git rev-parse --show-toplevel. Check python3 --version (3.9 or later). If docs/docs.json, docs/_templates/ or scripts/build_docs.py exists, list what is there and ask before going on. Look at how the site deploys (.github/workflows/, a site/ or public/ folder) so the output folder fits it.
2. Interview, briefly. Propose the defaults: eng (Engineering) and decisions (Decisions, written by the decisions module). Ask which spaces to keep or add, and the name, about line and owner of each. Ask for the output folder, URL prefix and base URL only when the defaults do not fit the deploy. One round of questions; do not ask for more than these fields.
3. Copy without overwriting.