3.7. Build processes
Up: 3. Developer guide
Prev: 3.6. Tasks
Next: 3.8. Running and creating tests
Sections:
Documentation build script
To regenerate the documentation, run make docs.
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 function extracts entries from the table of contents section in the index, and build_navigation computes the up, previous, and next relationships for each page. The 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, 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. 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 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.