7.5. Build processes
Up: 7. Developer guide
Prev: 7.4. Code policies
Next: 7.6. Running the server
Sections:
Documentation build script
To regenerate the documentation, run make docs. Pre-commit runs this too. Review and stage any
regenerated Markdown, then rerun.
The ATR documentation that you're reading right now is structured like a book, with numbered
chapters, sections, and navigation links between pages. We could maintain all of this by hand, but
that would be tedious and error-prone. Instead, we use
scripts/docs_build.py to generate the navigation automatically from
a single table of contents.
The script reads the table of contents in atr/docs/index.md, extracts
the hierarchy of pages, and then updates every referenced page to include the correct navigation
links, page numbers, and section listings. This means that when we want to reorganize the
documentation (say, inserting a new chapter or moving sections around) we only need to edit the
table of contents, run the script, and all the navigation is updated automatically.
The implementation is straightforward. The parse_toc (parse_toc)
function extracts entries from the table of contents section in the index, and
build_navigation (build_navigation) computes the up, previous, and
next relationships for each page. The update_document
(update_document) function is then called for each page, which rewrites the page heading to match
the canonical numbering from the index.md table of contents and injects a navigation block before
the first ## section.
The navigation block itself is generated by
generate_navigation_block (generate_navigation_block), which formats
the up, previous, and next links, adds a list of subpages if any exist, and includes a table of
contents for the page's sections as extracted by extract_h2_headings
(extract_h2_headings). This keeps all of the navigational machinery separate from the actual
content, which starts at the first ## heading.
We also validate that every page in the table of contents exists, and that there are no unlinked
Markdown files in the documentation directory. The validate_files
(validate_files) function performs these checks and fails with a descriptive error if anything is
wrong. This prevents us from accidentally forgetting to add a page to the table of contents, or from
leaving old pages lying around that we meant to delete.