This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/main by this push:
new 6e9c40d docs: fix links in build-process.md
6e9c40d is described below
commit 6e9c40ddd98c460517b73371202a3d6002b98b6d
Author: John Bampton <[email protected]>
AuthorDate: Sat Nov 15 23:20:00 2025 +1000
docs: fix links in build-process.md
---
atr/docs/build-processes.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/atr/docs/build-processes.md b/atr/docs/build-processes.md
index 1dd20c7..7368141 100644
--- a/atr/docs/build-processes.md
+++ b/atr/docs/build-processes.md
@@ -14,12 +14,12 @@
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/build_docs.py`](/ref/scripts/build_docs.py) to
generate the navigation automatically from a single table of contents.
+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`](/ref/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`](/ref/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`](/ref/scripts/build_docs.py:parse_toc) function extracts entries
from the table of contents section in the index, and
[`build_navigation`](/ref/scripts/build_docs.py:build_navigation) computes the
up, previous, and next relationships for each page. The
[`update_document`](/ref/scripts/build_docs.py:update_document) function is
then called for each page, which rewrites the page heading to match the
canonical numbering from the `index [...]
+The implementation is straightforward. The
[`parse_toc`](/ref/scripts/docs_build.py:parse_toc) function extracts entries
from the table of contents section in the index, and
[`build_navigation`](/ref/scripts/docs_build.py:build_navigation) computes the
up, previous, and next relationships for each page. The
[`update_document`](/ref/scripts/docs_build.py:update_document) function is
then called for each page, which rewrites the page heading to match the
canonical numbering from the `index [...]
-The navigation block itself is generated by
[`generate_navigation_block`](/ref/scripts/build_docs.py: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`](/ref/scripts/build_docs.py:extract_h2_headings). This
keeps all of the navigational machinery separate from the actual content, which
starts at the first `##` heading.
+The navigation block itself is generated by
[`generate_navigation_block`](/ref/scripts/docs_build.py: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`](/ref/scripts/docs_build.py: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`](/ref/scripts/build_docs.py: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.
+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`](/ref/scripts/docs_build.py: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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
