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 41640d2 Add a note about how to regenerate the documentation
41640d2 is described below
commit 41640d29953e403beafcd386004c4b6d4544435c
Author: Sean B. Palmer <[email protected]>
AuthorDate: Fri Oct 24 08:51:10 2025 +0100
Add a note about how to regenerate the documentation
---
atr/docs/build-processes.html | 1 +
atr/docs/build-processes.md | 2 ++
2 files changed, 3 insertions(+)
diff --git a/atr/docs/build-processes.html b/atr/docs/build-processes.html
index 82d8c93..6a5f1cb 100644
--- a/atr/docs/build-processes.html
+++ b/atr/docs/build-processes.html
@@ -7,6 +7,7 @@
<li><a href="#documentation-build-script">Documentation build script</a></li>
</ul>
<h2 id="documentation-build-script">Documentation build script</h2>
+<p>To <strong>regenerate the documentation</strong>, run <code>make
docs</code>.</p>
<p>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 <a
href="/ref/scripts/build_docs.py"><code>scripts/build_docs.py</code></a> to
generate the navigation automatically from a single table of contents.</p>
<p>The script reads the table of contents in <a
href="/ref/atr/docs/index.md"><code>atr/docs/index.md</code></a>, 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.</p>
<p>The implementation is straightforward. The <a
href="/ref/scripts/build_docs.py:parse_toc"><code>parse_toc</code></a> function
extracts entries from the table of contents section in the index, and <a
href="/ref/scripts/build_docs.py:build_navigation"><code>build_navigation</code></a>
computes the up, previous, and next relationships for each page. The <a
href="/ref/scripts/build_docs.py:update_document"><code>update_document</code></a>
function is then called for each page, which rewri [...]
diff --git a/atr/docs/build-processes.md b/atr/docs/build-processes.md
index c73de00..b910b10 100644
--- a/atr/docs/build-processes.md
+++ b/atr/docs/build-processes.md
@@ -12,6 +12,8 @@
## 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/build_docs.py`](/ref/scripts/build_docs.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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
