You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by sb...@apache.org on 2025/11/28 19:17:11 UTC

(tooling-trusted-releases) branch main updated: Move HTML generation to the containers and use an ignored directory

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 ee5a3bf  Move HTML generation to the containers and use an ignored directory
ee5a3bf is described below

commit ee5a3bfe442ac9317ca0f427e335945ab397ebfd
Author: Sean B. Palmer <se...@miscoranda.com>
AuthorDate: Fri Nov 28 19:16:34 2025 +0000

    Move HTML generation to the containers and use an ignored directory
---
 .gitignore                               |   1 +
 Dockerfile.alpine                        |   3 +
 Dockerfile.ubuntu                        |   3 +
 Makefile                                 |  10 +-
 atr/docs/build-processes.html            |  15 ---
 atr/docs/code-conventions.html           | 181 -------------------------
 atr/docs/database.html                   |  35 -----
 atr/docs/developer-guide.html            |  23 ----
 atr/docs/how-to-contribute.html          | 103 ---------------
 atr/docs/index.html                      |  22 ----
 atr/docs/introduction-to-atr.html        |  27 ----
 atr/docs/overview-of-the-code.html       |  46 -------
 atr/docs/running-and-creating-tests.html |  36 -----
 atr/docs/running-the-server.html         |  55 --------
 atr/docs/storage-interface.html          | 100 --------------
 atr/docs/tasks.html                      |  53 --------
 atr/docs/user-guide.html                 |  10 --
 atr/docs/user-interface.html             | 218 -------------------------------
 atr/get/docs.py                          |   2 +-
 19 files changed, 12 insertions(+), 931 deletions(-)

diff --git a/.gitignore b/.gitignore
index 0c7bf91..53a261d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,7 @@ apptoken.txt
 atr/_version.py
 bootstrap/build/
 dev/
+docs/
 node_modules/
 package-lock.json
 state/
diff --git a/Dockerfile.alpine b/Dockerfile.alpine
index 87b8032..70ee3e3 100644
--- a/Dockerfile.alpine
+++ b/Dockerfile.alpine
@@ -8,6 +8,7 @@ ENV PIP_DEFAULT_TIMEOUT=100 \
 
 RUN apk update && \
     apk add --no-cache \
+      cmark \
       git \
       make \
       patch
@@ -25,6 +26,7 @@ RUN make sync
 
 # generate a version.py module from git information
 RUN make generate-version
+RUN make docs
 
 WORKDIR /opt/atr/.venv/lib/python3.13/site-packages
 RUN patch -p2 < /opt/atr/patches/generics.py.patch
@@ -59,6 +61,7 @@ WORKDIR /opt/atr
 # copy app and wheels from builder
 COPY --from=builder /opt/atr/.venv ./.venv
 COPY --from=builder /opt/atr/atr ./atr
+COPY --from=builder /opt/atr/docs ./docs
 COPY --from=builder /opt/atr/migrations ./migrations
 COPY --from=builder /opt/atr/patches ./patches
 COPY --from=builder /opt/atr/scripts ./scripts
diff --git a/Dockerfile.ubuntu b/Dockerfile.ubuntu
index 57f7a42..f48f381 100644
--- a/Dockerfile.ubuntu
+++ b/Dockerfile.ubuntu
@@ -9,6 +9,7 @@ ENV PIP_DEFAULT_TIMEOUT=100 \
 
 RUN apt-get update && \
     apt-get install -y \
+      cmark \
       git \
       make \
       patch \
@@ -33,6 +34,7 @@ RUN make sync
 
 # generate a version.py module from git information
 RUN make generate-version
+RUN make docs
 
 WORKDIR /opt/atr/.venv/lib/python3.13/site-packages
 RUN patch -p2 < /opt/atr/patches/generics.py.patch
@@ -73,6 +75,7 @@ WORKDIR /opt/atr
 # copy app and wheels from builder
 COPY --from=builder /opt/atr/.venv ./.venv
 COPY --from=builder /opt/atr/atr ./atr
+COPY --from=builder /opt/atr/docs ./docs
 COPY --from=builder /opt/atr/migrations ./migrations
 COPY --from=builder /opt/atr/scripts ./scripts
 COPY --from=builder /opt/atr/Makefile .
diff --git a/Makefile b/Makefile
index 3bb6f1b..624ac17 100644
--- a/Makefile
+++ b/Makefile
@@ -48,14 +48,12 @@ commit:
 	git push
 
 docs:
+	mkdir -p docs
 	uv run python3 scripts/docs_check.py
-	rm -f atr/docs/*.html
+	rm -f docs/*.html
 	uv run python3 scripts/docs_build.py
-	for fn in atr/docs/*.md; \
-	do \
-	  cmark "$$fn" > "$${fn%.md}.html"; \
-	done
-	uv run python3 scripts/docs_post_process.py atr/docs/*.html
+	for fn in atr/docs/*.md; do out=$${fn#atr/}; cmark "$$fn" > "$${out%.md}.html"; done
+	uv run python3 scripts/docs_post_process.py docs/*.html
 	uv run python3 scripts/docs_check.py
 
 generate-version:
diff --git a/atr/docs/build-processes.html b/atr/docs/build-processes.html
deleted file mode 100644
index 4dec9fc..0000000
--- a/atr/docs/build-processes.html
+++ /dev/null
@@ -1,15 +0,0 @@
-<h1 id="build-processes">3.7. Build processes</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.6.</code> <a href="tasks">Tasks</a></p>
-<p><strong>Next</strong>: <code>3.8.</code> <a href="running-and-creating-tests">Running and creating tests</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<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/docs_build.py"><code>scripts/docs_build.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/docs_build.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/docs_build.py:build_navigation"><code>build_navigation</code></a> computes the up, previous, and next relationships for each page. The <a href="/ref/scripts/docs_build.py:update_document"><code>update_document</code></a> function is then called for each page, which rewri [...]
-<p>The navigation block itself is generated by <a href="/ref/scripts/docs_build.py:generate_navigation_block"><code>generate_navigation_block</code></a>, 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 <a href="/ref/scripts/docs_build.py:extract_h2_headings"><code>extract_h2_headings</code></a>. This keeps all of the navigational machinery separate from the actual content, which [...]
-<p>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 <a href="/ref/scripts/docs_build.py:validate_files"><code>validate_files</code></a> 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.</p>
diff --git a/atr/docs/code-conventions.html b/atr/docs/code-conventions.html
deleted file mode 100644
index ff38331..0000000
--- a/atr/docs/code-conventions.html
+++ /dev/null
@@ -1,181 +0,0 @@
-<h1 id="code-conventions">3.9. Code conventions</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.8.</code> <a href="running-and-creating-tests">Running and creating tests</a></p>
-<p><strong>Next</strong>: <code>3.10.</code> <a href="how-to-contribute">How to contribute</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#python-code">Python code</a></li>
-<li><a href="#html">HTML</a></li>
-<li><a href="#markdown">Markdown</a></li>
-<li><a href="#javascript">JavaScript</a></li>
-</ul>
-<h2 id="python-code">Python code</h2>
-<h3 id="follow-pep-8-rules-by-default">Follow PEP 8 rules by default</h3>
-<p>Follow <a href="https://peps.python.org/pep-0008/">PEP 8</a> unless otherwise indicated in this document. Some of the conventions listed below recapitulate or add exceptions to PEP 8 rules.</p>
-<p>Obey all project local lints, e.g. the use of <code>ruff</code> and specific <code>ruff</code> rules.</p>
-<h3 id="keep-the-primary-execution-path-to-the-left">Keep the primary execution path to the left</h3>
-<p>Structure code so that the most likely, normal, successful execution path remains at the level of least indentation. Handle error cases and edge conditions early with guard clauses, and then continue with the main logic. This makes it easier to identify the primary execution flow.</p>
-<pre><code class="language-python"># Avoid
-def process_data(data):
-    if data is not None:
-        if len(data) &gt; 0:
-            if validate(data):
-                return transform(data)
-            else:
-                raise ValueError("Invalid data")
-        else:
-            raise ValueError("Empty data")
-    else:
-        raise ValueError("No data")
-
-# Prefer
-def process_data(data):
-    if data is None:
-        raise ValueError("No data")
-    if len(data) == 0:
-        raise ValueError("Empty data")
-    if not validate(data):
-        raise ValueError("Invalid data")
-
-    return transform(data)
-</code></pre>
-<h3 id="avoid-excessive-indentation">Avoid excessive indentation</h3>
-<p>When you find yourself nesting code more than two or three levels deep, extract the nested logic into separate functions. This improves readability, testability, and maintainability. Each function should handle a single, well defined piece of logic.</p>
-<h3 id="do-not-use-lint-or-type-checker-ignore-statements">Do not use lint or type checker ignore statements</h3>
-<p>You must not use <code># noqa</code>, <code># type: ignore</code>, or equivalents such as <code>cast</code>, even to ignore specific errors. The single exception to this is when there is a bug in the linter or type checker.</p>
-<p>File level lint ignores can be added to the project's <code>pyproject.toml</code>, but they must be used sparingly.</p>
-<h3 id="use-double-quotes-for-all-strings">Use double quotes for all strings</h3>
-<p>This includes triple quoted strings.</p>
-<h3 id="prefix-private-interfaces-with-a-single-underscore">Prefix private interfaces with a single underscore</h3>
-<p>Prefix all private interfaces, e.g. functions, classes, constants, variables, with a single underscore. An interface is private when used exclusively within its containing module and not referenced by external code, templates, or processes.</p>
-<p>Exceptions to this rule include:</p>
-<ul>
-<li>Type variables</li>
-<li>Enumerations</li>
-<li>Methods requiring interface compatibility with their superclass</li>
-<li>Nested functions (which should generally be avoided)</li>
-</ul>
-<p>Scripts are explicitly <em>not</em> an exception. Underscores should be used to prefix private interfaces in scripts for consistency, e.g. so that linters don't need to carry exceptions, and to ease potential migration to modules.</p>
-<h3 id="avoid-nested-functions">Avoid nested functions</h3>
-<p>Function definitions should be at the top level. This is not a hard rule, but should only be broken when absolutely necessary.</p>
-<h3 id="use-uppercase-for-top-level-constants">Use UPPERCASE for top level constants</h3>
-<p>Define top level constants using <code>UPPERCASE</code> letters. Don't forget to apply an underscore prefix to constants which are private to their module.</p>
-<p>Do not use uppercase for constants within functions and methods.</p>
-<code></code><h3 id="use-the-final-type-with-all-constants">Use the Final type with all constants</h3>
-<p>This pattern must be followed for top level constants, and should be followed for function and method level constants too. The longer the function, the more important the use of <code>Final</code>.</p>
-<code></code><h3 id="prefix-global-variables-with-global">Prefix global variables with global_</h3>
-<p>Top level variables should be avoided. When their use is necessary, prefix them with <code>global_</code>, using lowercase letters, to ensure clear identification of their scope. Use an underscore prefix too, <code>_global_</code>, when the variable is private.</p>
-<h3 id="import-modules-as-their-least-significant-name-part">Import modules as their least significant name part</h3>
-<p>Import modules using their least significant name component:</p>
-<pre><code class="language-python"># Prefer
-import a.b.c as c
-
-# Avoid
-import a.b.c
-</code></pre>
-<p>This convention aligns with Go's package naming practices. Follow <a href="https://go.dev/blog/package-names">Go naming rules</a> for all modules.</p>
-<p>This only applies to modules outside of the Python standard library. The standard library module <code>os.path</code>, for example, must always be imported using the form <code>import os.path</code>, and <em>not</em> <code>import os.path as path</code>.</p>
-<p>Furthermore, if a third party module to be imported would conflict with a Python standard library module, then that third party module must be imported with one extra level.</p>
-<pre><code class="language-python"># Prefer
-import asyncio.subprocess
-import sqlalchemy.ext as ext
-import aiofiles.os
-
-# Avoid
-import asyncio.subprocess as subprocess
-import sqlalchemy.ext.asyncio as asyncio
-import aiofiles.os.path as path
-</code></pre>
-<p>It's possible to use <code>from a.b import c</code> instead of <code>import a.b.c as c</code> when <code>c</code> is a module, but we prefer the latter form because it makes it clear that <code>c</code> must be a module, whereas in the former <code>from a.b import c</code> form, <code>c</code> could be any interface.</p>
-<p>TODO: There's a question as to whether we could actually use <code>import aiofiles.os.path as path</code> since we import <code>os.path</code> as <code>os.path</code> and not <code>path</code>.</p>
-<p>TODO: Sometimes we're using <code>as</code> for standard library modules. We should decide what to do about this.</p>
-<h3 id="avoid-duplicated-module-names">Avoid duplicated module names</h3>
-<p>Try to avoid using, for example, <code>baking/apple/pie.py</code> and <code>baking/cherry/pie.py</code> because these will both be imported as <code>pie</code> and one will have to be renamed.</p>
-<p>If there are duplicates imported within a single file, they should be disambiguated by the next level up. In the pie example, that would be <code>import baking.apple as apple</code> and then <code>apple.pie</code>, and <code>import baking.cherry as cherry</code> and <code>cherry.pie</code>.</p>
-<h3 id="never-import-names-directly-from-modules">Never import names directly from modules</h3>
-<p>Avoid importing specific names from modules:</p>
-<pre><code class="language-python"># Prefer
-import p.q.r as r
-r.s()
-
-# Avoid
-from p.q.r import s
-s()
-</code></pre>
-<p>The <code>collections.abc</code>, <code>types</code>, and <code>typing</code> modules are an exception to this rule. Always import <code>collections.abc</code>, <code>types</code> and <code>typing</code> interfaces directly using the <code>from</code> syntax:</p>
-<pre><code class="language-python"># Prefer
-from typing import Final
-
-CONSTANT: Final = "CONSTANT"
-
-# Avoid
-import typing
-
-CONSTANT: typing.Final = "CONSTANT"
-</code></pre>
-<h3 id="use-concise-typing-patterns">Use concise typing patterns</h3>
-<p>Do not use <code>List</code> or <code>Optional</code> etc. from the typing module.</p>
-<pre><code class="language-python"># Prefer
-def example() -&gt; list[str | None]:
-    return ["a", "c", None]
-
-# Avoid
-from typing import List, Optional
-
-def example() -&gt; List[Optional[str]]:
-    return ["a", "c", None]
-</code></pre>
-<h3 id="never-name-interfaces-after-their-module">Never name interfaces after their module</h3>
-<p>Do not name interfaces with the same identifier as their containing module. For example, in a module named <code>example</code>, the function names <code>example</code> and <code>example_function</code> are prohibited.</p>
-<h3 id="keep-modules-small-and-focused">Keep modules small and focused</h3>
-<p>Maintain modules with a reasonable number of interfaces. Though no strict limits are enforced, modules containing numerous classes, constants, or functions should be considered for logical subdivision. Exceptions may be made when closely related functionality necessitates grouping multiple interfaces within a single module.</p>
-<h3 id="sort-functions-alphabetically">Sort functions alphabetically</h3>
-<p>Wherever possible, the order of functions within each module should be alphabetical by name. Take advantage of this convention by grouping related functions under a common prefix (including grouping helper functions with their caller), and using numbers in the names of functions called in serial order.</p>
-<h3 id="keep-cyclomatic-complexity-below-10">Keep cyclomatic complexity below 10</h3>
-<p>We limit function complexity to a score of 10. If the linter complains, your function is doing too much.</p>
-<p>Cyclomatic complexity counts the number of independent paths through code: more if and else branches, loops, and exception handlers means higher complexity. Complex code is harder to test, maintain, and understand. The easiest way to fix high complexity is usually to refactor a chunk of related logic into a separate helper function.</p>
-<h3 id="replace-synchronous-calls-with-asynchronous-counterparts-in-async-code">Replace synchronous calls with asynchronous counterparts in async code</h3>
-<p>Our use of blockbuster enables automatic detection of synchronous function calls within asynchronous code. When detected, replace these calls with their asynchronous equivalents without performance testing. The conversion process typically requires minimal, trivial effort.</p>
-<p>Exceptions to this rule apply only in these scenarios:</p>
-<ul>
-<li>When dealing with third party dependencies</li>
-<li>When the asynchronous equivalent function is unknown</li>
-</ul>
-<p>If either exception applies, either submit a brief issue with the blockbuster traceback, notify the team via Slack, or add a code comment if part of another commit. An ATR Tooling engineer will address the issue without requiring significant time investment from you.</p>
-<h3 id="always-use-parentheses-to-group-complex-nested-subexpressions">Always use parentheses to group complex nested subexpressions</h3>
-<p>Complex subexpressions are those which contain a keyword or operator.</p>
-<pre><code class="language-python"># Avoid
-a or b and c == d or not e or f
-
-# Prefer
-(a or b) and (c == d) or (not e) or f
-</code></pre>
-<p>Because <code>f</code> is not a complex expression, it does not get parenthesised. Also because this rule is about subexpressions only, we do not put parentheses around the top level.</p>
-<pre><code class="language-python"># Avoid
-if (a or b):
-    ...
-
-# Prefer
-if a or b:
-    ...
-</code></pre>
-<h3 id="use-terse-comments-on-their-own-lines">Use terse comments on their own lines</h3>
-<p>Place comments on dedicated lines preceding the relevant code block. Comments at the ends of lines are strictly reserved for linter or type checker directives. This convention enhances code scannability for such directives. General comments must not appear at the end of code lines. Keep comments concise, using sentence case without terminal punctuation. Each sentence forming a comment must occupy its own line. Comments must not include information about what has changed from earlier c [...]
-<code></code><h3 id="prefer-explicit-checks-over-assert">Prefer explicit checks over assert</h3>
-<p>We do not use <code>assert</code>. If you need to guard against invalid states or inputs, use standard <code>if</code> checks and raise appropriate exceptions. If you need to help type checkers understand the type of a variable within a specific code block, in other words if you need to narrow a type, then use <code>if isinstance(...)</code> or <code>if not isinstance(...)</code> as appropriate.</p>
-<code></code><h3 id="never-use-case-when-pattern-matching-exhaustive-types">Never use case _ when pattern matching exhaustive types</h3>
-<p>Using <code>case _</code> breaks type checking in such situations.</p>
-<h3 id="use-f-string-interpolation-instead-of-printf-style-formatting">Use f-string interpolation instead of printf style formatting</h3>
-<p>This should be adhered to even in contexts where printf style is usually expected, such as in <code>log.info</code> calls, unless there is a reason not to, such as when there are specific printf style flags which have no f-string equivalent.</p>
-<p>This convention is not enforced by any checks. Enforcement is via code review. See <a href="https://github.com/apache/tooling-trusted-releases/issues/339">issue #339</a> for a discussion.</p>
-<h2 id="html">HTML</h2>
-<h3 id="use-sentence-case-for-headings-form-labels-and-submission-buttons">Use sentence case for headings, form labels, and submission buttons</h3>
-<p>We write headings, form labels, and submission buttons in the form "This is some text", and not "This is Some Text" or "This Is Some Text". This follows the <a href="https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Section_headings">Wikipedia style for headings</a>.</p>
-<h3 id="use-bootstrap-classes-for-all-style">Use Bootstrap classes for all style</h3>
-<p>We use Bootstrap classes for style, and avoid custom classes unless absolutely necessary. If you think that you have to resort to a custom class, consult the list of <a href="https://bootstrapclasses.com/">Bootstrap classes</a> for guidance. There is usually a class for what you want to achieve, and if there isn't then you may be making things too complicated. Complicated, custom style is difficult for a team to maintain. If you still believe that a new class is strictly warranted, th [...]
-<h2 id="markdown">Markdown</h2>
-<code></code><code></code><h3 id="use-for-emphasis-and-for-strong-emphasis">Use _ for emphasis and ** for strong emphasis</h3>
-<p>Do not use <code>*</code> for emphasis or <code>__</code> for strong emphasis.</p>
-<h2 id="javascript">JavaScript</h2>
-<h3 id="do-not-use-javascript-unless-necessary">Do not use JavaScript unless necessary</h3>
-<p>It is often possible to avoid using JavaScript without significant loss of functionality, but it may require a little more thought. JavaScript is not, however, something to avoid by rote. User experiences can be significantly improved with thoughtful application of JavaScript. Therefore, default to not using JavaScript, but consider how it could be used concisely and with care to improve UX.</p>
diff --git a/atr/docs/database.html b/atr/docs/database.html
deleted file mode 100644
index 1db1eb5..0000000
--- a/atr/docs/database.html
+++ /dev/null
@@ -1,35 +0,0 @@
-<h1 id="database">3.3. Database</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.2.</code> <a href="overview-of-the-code">Overview of the code</a></p>
-<p><strong>Next</strong>: <code>3.4.</code> <a href="storage-interface">Storage interface</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-<li><a href="#core-models">Core models</a></li>
-<li><a href="#other-features">Other features</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>ATR stores all of its data in a SQLite database. The database schema is defined in <a href="/ref/atr/models/sql.py"><code>models.sql</code></a> using <a href="https://sqlmodel.tiangolo.com/">SQLModel</a>, which uses <a href="https://docs.pydantic.dev/latest/">Pydantic</a> for data validation and <a href="https://www.sqlalchemy.org/">SQLAlchemy</a> for database operations. This page explains the main features of the database schema to help you understand how data is structured in ATR.</p>
-<h2 id="core-models">Core models</h2>
-<p>The three most important models in ATR are <a href="/ref/atr/models/sql.py:Committee"><code>Committee</code></a>, <a href="/ref/atr/models/sql.py:Project"><code>Project</code></a>, and <a href="/ref/atr/models/sql.py:Release"><code>Release</code></a>.</p>
-<p>A <a href="/ref/atr/models/sql.py:Committee"><code>Committee</code></a> represents a PMC or PPMC at the ASF. Each committee has a name, which is the primary key, and a full name for display purposes. Committees can have child committees, which is used for the relationship between the Incubator PMC and individual podling PPMCs. Committees also have lists of committee members and committers stored as JSON arrays.</p>
-<p>A <a href="/ref/atr/models/sql.py:Project"><code>Project</code></a> belongs to a committee and can have multiple releases. Projects have a name as the primary key, along with metadata such as a description and category and programming language tags. Each project can optionally have a <a href="/ref/atr/models/sql.py:ReleasePolicy"><code>ReleasePolicy</code></a> that defines how releases should be handled, including e.g. vote templates and GitHub workflow configuration.</p>
-<p>A <a href="/ref/atr/models/sql.py:Release"><code>Release</code></a> belongs to a project and represents a specific version of software which is voted on by a committee. The primary key is a name derived from the project name and version. Releases have a phase that indicates their current state in the release process, from draft composition to final publication. Each release can have multiple <a href="/ref/atr/models/sql.py:Revision"><code>Revision</code></a> instances before final pub [...]
-<h2 id="other-features">Other features</h2>
-<p>The models themselves are the most important components, but to support those models we need other components such as enumerations, column types, automatically populated fields, computed properties, and constraints.</p>
-<h3 id="enumerations">Enumerations</h3>
-<p>ATR uses Python enumerations to ensure that certain fields only contain valid values. The most important enumeration is <a href="/ref/atr/models/sql.py:ReleasePhase"><code>ReleasePhase</code></a>, which defines the four phases of a release: <code>RELEASE_CANDIDATE_DRAFT</code> for composing, <code>RELEASE_CANDIDATE</code> for voting, <code>RELEASE_PREVIEW</code> for finishing, and <code>RELEASE</code> for completed releases.</p>
-<p>The <a href="/ref/atr/models/sql.py:TaskStatus"><code>TaskStatus</code></a> enumeration defines the states a task can be in: <code>QUEUED</code>, <code>ACTIVE</code>, <code>COMPLETED</code>, or <code>FAILED</code>. The <a href="/ref/atr/models/sql.py:TaskType"><code>TaskType</code></a> enumeration lists all the different types of background tasks that ATR can execute, from signature checks to SBOM generation.</p>
-<p>The <a href="/ref/atr/models/sql.py:DistributionPlatform"><code>DistributionPlatform</code></a> enumeration is more complex, as each value contains not just a name but a <a href="/ref/atr/models/sql.py:DistributionPlatformValue"><code>DistributionPlatformValue</code></a> with template URLs and configuration for different package distribution platforms like PyPI, npm, and Maven Central.</p>
-<h3 id="special-column-types">Special column types</h3>
-<p>SQLite does not support all the data types we need, so we use SQLAlchemy type decorators to handle conversions. The <a href="/ref/atr/models/sql.py:UTCDateTime"><code>UTCDateTime</code></a> type ensures that all datetime values are stored in UTC and returned as timezone-aware datetime objects. When Python code provides a datetime with timezone information, the type decorator converts it to UTC before storing. When reading from the database, it adds back the UTC timezone information.</p>
-<p>The <a href="/ref/atr/models/sql.py:ResultsJSON"><code>ResultsJSON</code></a> type handles storing task results. It automatically serializes Pydantic models to JSON when writing to the database, and deserializes them back to the appropriate result model when reading.</p>
-<h3 id="automatic-field-population">Automatic field population</h3>
-<p>Some fields are populated automatically using SQLAlchemy event listeners. When a new <a href="/ref/atr/models/sql.py:Revision"><code>Revision</code></a> is created, the <a href="/ref/atr/models/sql.py:populate_revision_sequence_and_name"><code>populate_revision_sequence_and_name</code></a> function runs before the database insert. This function queries for the highest existing sequence number for the release, increments it, and sets both the <code>seq</code> and <code>number</code> fi [...]
-<p>The <a href="/ref/atr/models/sql.py:check_release_name"><code>check_release_name</code></a> function runs before inserting a release. If the release name is empty, it automatically generates it from the project name and version using the <a href="/ref/atr/models/sql.py:release_name"><code>release_name</code></a> helper function.</p>
-<h3 id="computed-properties">Computed properties</h3>
-<p>Some properties are computed dynamically rather than stored in the database. The <code>Release.latest_revision_number</code> property is implemented as a SQLAlchemy column property using a correlated subquery. This means that when you access <code>release.latest_revision_number</code>, SQLAlchemy automatically executes a query to find the highest revision number for that release. The query is defined once in <a href="/ref/atr/models/sql.py:RELEASE_LATEST_REVISION_NUMBER"><code>RELEASE [...]
-<p>Projects have many computed properties that provide access to release policy settings with appropriate defaults. For example, <code>Project.policy_start_vote_template</code> returns the custom vote template if one is configured, or falls back to <code>Project.policy_start_vote_default</code> if not. This pattern allows projects to customize their release process while providing sensible defaults.</p>
-<h3 id="constraints-and-validation">Constraints and validation</h3>
-<p>Database constraints ensure data integrity. The <a href="/ref/atr/models/sql.py:Task"><code>Task</code></a> model includes a check constraint that validates the status transitions. A task must start in <code>QUEUED</code> state, can only transition to <code>ACTIVE</code> when <code>started</code> and <code>pid</code> are set, and can only reach <code>COMPLETED</code> or <code>FAILED</code> when the <code>completed</code> timestamp is set. These constraints prevent invalid state transi [...]
-<p>Unique constraints ensure that certain combinations of fields are unique. The <code>Release</code> model has a unique constraint on <code>(project_name, version)</code> to prevent creating duplicate releases for the same project version. The <code>Revision</code> model has two unique constraints: one on <code>(release_name, seq)</code> and another on <code>(release_name, number)</code>, ensuring that revision numbers are unique within a release.</p>
diff --git a/atr/docs/developer-guide.html b/atr/docs/developer-guide.html
deleted file mode 100644
index f6e3f98..0000000
--- a/atr/docs/developer-guide.html
+++ /dev/null
@@ -1,23 +0,0 @@
-<h1 id="developer-guide">3. Developer guide</h1>
-<p><strong>Up</strong>: <a href=".">Documentation</a></p>
-<p><strong>Prev</strong>: <code>2.</code> <a href="user-guide">User guide</a></p>
-<p><strong>Next</strong>: (none)</p>
-<p><strong>Pages</strong>:</p>
-<ul>
-<li><code>3.1.</code> <a href="running-the-server">Running the server</a></li>
-<li><code>3.2.</code> <a href="overview-of-the-code">Overview of the code</a></li>
-<li><code>3.3.</code> <a href="database">Database</a></li>
-<li><code>3.4.</code> <a href="storage-interface">Storage interface</a></li>
-<li><code>3.5.</code> <a href="user-interface">User interface</a></li>
-<li><code>3.6.</code> <a href="tasks">Tasks</a></li>
-<li><code>3.7.</code> <a href="build-processes">Build processes</a></li>
-<li><code>3.8.</code> <a href="running-and-creating-tests">Running and creating tests</a></li>
-<li><code>3.9.</code> <a href="code-conventions">Code conventions</a></li>
-<li><code>3.10.</code> <a href="how-to-contribute">How to contribute</a></li>
-</ul>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>This is a guide for developers of ATR, explaining how to make changes to the ATR source code. For more information about how to contribute those changes back to us, please read the <a href="how-to-contribute">contribution guide</a>.</p>
diff --git a/atr/docs/how-to-contribute.html b/atr/docs/how-to-contribute.html
deleted file mode 100644
index ca36ef8..0000000
--- a/atr/docs/how-to-contribute.html
+++ /dev/null
@@ -1,103 +0,0 @@
-<h1 id="how-to-contribute">3.10. How to contribute</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.9.</code> <a href="code-conventions">Code conventions</a></p>
-<p><strong>Next</strong>: (none)</p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-<li><a href="#finding-something-to-work-on">Finding something to work on</a></li>
-<li><a href="#pull-request-workflow">Pull request workflow</a></li>
-<li><a href="#commit-message-style">Commit message style</a></li>
-<li><a href="#asf-contribution-policies">ASF contribution policies</a></li>
-<li><a href="#special-considerations-for-atr">Special considerations for ATR</a></li>
-<li><a href="#getting-help">Getting help</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>ATR is developed by ASF Tooling in public as open source code, and we welcome high quality contributions from external contributors. Whether you are fixing a typographical error in documentation, improving an error message, implementing a new feature, or addressing a security issue, your contribution helps to improve ATR for all of our users.</p>
-<p>This page explains how to contribute code and documentation to ATR. We recommend reading the <a href="introduction-to-atr">platform introduction</a> and <a href="overview-of-the-code">overview of the code</a> first to understand the purpose of ATR and how the codebase is structured. You should also read the <a href="code-conventions">code conventions</a> page; we expect all contributions to follow those conventions.</p>
-<h2 id="finding-something-to-work-on">Finding something to work on</h2>
-<p>The easiest way to find something to work on is to look at our <a href="https://github.com/apache/tooling-trusted-releases/issues">issue tracker</a> on GitHub. We label <a href="https://github.com/apache/tooling-trusted-releases/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22">issues that are suitable for new contributors</a> as <code>good first issue</code>. These are typically small, well-defined tasks that do not require deep familiarity with the entire code [...]
-<p>If you find a bug that is not already reported in the issue tracker, or if you have an idea for a new feature, please <a href="https://github.com/apache/tooling-trusted-releases/issues/new">create a new issue</a> to discuss it with other developers before you start working on it. This helps to ensure that your contribution will be accepted, and that you do not duplicate work that is already in progress. For small changes such as fixing typographical errors or improving documentation c [...]
-<h2 id="pull-request-workflow">Pull request workflow</h2>
-<p>Once you have identified something to work on, the process of contributing is as follows:</p>
-<ol>
-<li>
-<p><strong>Fork the repository.</strong> Create a personal fork of the <a href="https://github.com/apache/tooling-trusted-releases">ATR repository</a> on GitHub.</p>
-</li>
-<li>
-<p><strong>Clone your fork.</strong> Clone your fork to your local machine and set up your development environment. Follow the instructions in the <a href="running-the-server">running the server</a> guide to get ATR running locally. Please <a href="#getting-help">ask us for help</a> if you encounter any problems with this step.</p>
-</li>
-<li>
-<p><strong>Create a branch.</strong> <a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository">Create a new branch</a> for your work. Use a descriptive name that indicates what you are working on, such as <code>fix-typo-in-docs</code> or <code>improve-error-messages</code>.</p>
-</li>
-<li>
-<p><strong>Make your changes.</strong> Implement your fix or feature, following our <a href="code-conventions">code conventions</a>. If you are changing code, ensure that your changes do not break existing functionality. Whenever you change code, and especially if you are adding a new feature, consider <a href="running-and-creating-tests">adding a test</a>.</p>
-</li>
-<li>
-<p><strong>Commit your changes.</strong> Write clear, concise commit messages following <a href="#commit-message-style">our commit message style</a>. Each commit should represent a logical unit of work, but we are not particularly strict about this.</p>
-</li>
-<li>
-<p><strong>Push your branch.</strong> Push your branch to your fork on GitHub.</p>
-</li>
-<li>
-<p><strong>Create a pull request (PR).</strong> The PR should be from your branch to the <code>main</code> branch of the ATR repository. In the PR description, explain what your changes do and why they are needed. If your PR addresses an existing issue, reference that issue by number.</p>
-</li>
-<li>
-<p><strong>Participate in code review.</strong> A member of the Tooling team will review your PR and may request changes. <em>We strongly recommend enabling the option to allow maintainers to edit your PR when you create it.</em> Even if you allow us to make changes, we may still ask you to make the changes yourself. Also, because of the stringent security and usability requirements for ATR, we accept only <a href="#special-considerations-for-atr">high quality contributions</a>.</p>
-</li>
-</ol>
-<p>You can also <a href="https://lists.apache.org/list.html?dev@tooling.apache.org">email patches</a> if you prefer not to use GitHub. Please use standard Git patch formatting, as if you were e.g. contributing to the Linux Kernel.</p>
-<h2 id="commit-message-style">Commit message style</h2>
-<p>We follow a consistent style for commit messages. The first line of the commit message is called the subject line, and should follow these guidelines:</p>
-<ul>
-<li><strong>Use the imperative mood.</strong> The subject line should complete the sentence "If applied, this commit will...".</li>
-<li><strong>Use sentence case.</strong> Start with a capital letter, but do not use a full stop at the end.</li>
-<li><strong>Use articles as appropriate before nouns</strong>. Write about "a feature" not just "feature". Say, for example, "fix a bug", and not "fix bug".</li>
-<li><strong>Be specific and descriptive.</strong> Prefer "Fix a bug in vote resolution for tied votes" to "Fix a bug" or "Update the vote code".</li>
-<li><strong>Keep it concise.</strong> Aim for 50 to 72 characters. If you need more space to explain your changes, use the commit body.</li>
-</ul>
-<p><strong>Examples of good subject lines:</strong></p>
-<pre><code>Add distribution platform validation to the compose phase
-Fix a bug with sorting version numbers containing release candidates
-Move code to delete releases to the storage interface
-Update dependencies
-</code></pre>
-<p><strong>Examples of poor subject lines:</strong></p>
-<pre><code>fixed stuff
-Updated the code.
-refactoring vote resolution logic
-</code></pre>
-<p>Most commits do not need a body. The subject line alone is sufficient for small, focused changes. If, however, your commit is complex or requires additional explanation, add a body separated from the subject line by a blank line. In the body, explain what the change does and why it was necessary. We typically use itemized lists for this, using asterisks. You do not need to explain how the change works.</p>
-<h2 id="asf-contribution-policies">ASF contribution policies</h2>
-<p>As an Apache Software Foundation project, ATR follows the standard ASF contribution and licensing policies. These policies ensure that the ASF has the necessary rights to distribute your contributions, and that contributors retain their rights to use their contributions for other purposes.</p>
-<h3 id="contributor-license-agreement">Contributor License Agreement</h3>
-<p>Before we can accept your first contribution as an individual contributor, you must sign the <a href="https://www.apache.org/licenses/contributor-agreements.html#clas">Apache Individual Contributor License Agreement</a> (ICLA). This is a one-time requirement, and you do not need to sign a new ICLA for each contribution. The ICLA grants the ASF the right to distribute and build upon your work within Apache, while you retain full rights to use your original contributions for any other p [...]
-<p>If your employer holds rights to your work, then you may also need to submit a <a href="https://www.apache.org/licenses/contributor-agreements.html#clas">Corporate Contributor License Agreement</a> (CCLA). Please consult with your employer to determine whether this is necessary.</p>
-<h3 id="licensing">Licensing</h3>
-<p>All contributions to ATR are licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License 2.0</a>. By submitting a pull request, you agree that your contributions will be licensed under this license. If you include any third party code or dependencies in your contribution, you must ensure that they are compatible with the Apache License 2.0. The ASF maintains a list of <a href="https://www.apache.org/legal/resolved.html#category-a">Category A licenses</a> th [...]
-<h3 id="code-of-conduct">Code of conduct</h3>
-<p>All contributors to ATR are expected to follow the <a href="https://www.apache.org/foundation/policies/conduct.html">ASF Code of Conduct</a>, and any other applicable policies of the ASF.</p>
-<h2 id="special-considerations-for-atr">Special considerations for ATR</h2>
-<p>ATR is developed by ASF Tooling, which is an initiative of the ASF rather than a top-level project (TLP). This means that ATR follows the development processes and governance structure of Tooling, which may differ slightly from those of other ASF projects. There are also significant security considerations for ATR, which places additional requirements on contributions.</p>
-<h3 id="security-focus">Security focus</h3>
-<p>The primary goal of ATR is to deter and minimize supply chain attacks on ASF software releases. Since security is our highest priority, we scrutinize all contributions for potential vulnerabilities. To assist us when you make a contribution, please:</p>
-<ul>
-<li>Follow secure coding practices. Review best practice guidelines to learn how to avoid vulnerabilities such as injection attacks, cross-site scripting, and insecure deserialization.</li>
-<li>Validate all user inputs and sanitize all outputs.</li>
-<li>Use well established, independently audited, and actively maintained libraries rather than implementing cryptographic or security sensitive functionality yourself.</li>
-<li>Always consider the security implications of your changes. If you are unsure of the implications of your changes, ask the team for guidance.</li>
-<li>Report any security issues you discover in ATR responsibly. Do not open a public issue for security vulnerabilities. Instead, follow the <a href="https://www.apache.org/security/">ASF security reporting process</a>.</li>
-</ul>
-<h3 id="high-quality-standards">High quality standards</h3>
-<p>Because of the critical nature of ATR, we maintain very high standards for code quality. This means that the review process may take longer than you expect, and we may request more extensive changes than you are accustomed to. We appreciate your patience and understanding. Our goal is to ensure that ATR remains as secure and reliable as possible.</p>
-<h3 id="access-controls">Access controls</h3>
-<p>We strongly encourage all contributors to enable two-factor authentication on their GitHub accounts, preferably with a <a href="https://en.wikipedia.org/wiki/WebAuthn#Passkey_branding">passkey</a>.</p>
-<h2 id="getting-help">Getting help</h2>
-<p>If you have questions about contributing to ATR, or if you need help with any step of the contribution process, please reach out to the team. You can:</p>
-<ul>
-<li>Ask questions on the <a href="https://lists.apache.org/list.html?dev@tooling.apache.org">dev mailing list</a>, which is the primary forum for ATR development discussions.</li>
-<li>Comment on the relevant issue or pull request in the <a href="https://github.com/apache/tooling-trusted-releases/issues">issue tracker</a>.</li>
-<li>Chat with us in the <a href="https://the-asf.slack.com/archives/C049WADAAQG">#apache-trusted-releases channel</a> on ASF Slack.</li>
-<li>Read the rest of the <a href="developer-guide">developer guide</a> for detailed information about how ATR works and how to make changes to it.</li>
-</ul>
-<p>We welcome all types of contribution, and are happy to help you get started. Thank you for your interest in contributing to ATR.</p>
diff --git a/atr/docs/index.html b/atr/docs/index.html
deleted file mode 100644
index a043467..0000000
--- a/atr/docs/index.html
+++ /dev/null
@@ -1,22 +0,0 @@
-<h1 id="apache-trusted-releases-atr-documentation">Apache Trusted Releases (ATR) documentation</h1>
-<p>Welcome to the documentation for the <strong>ATR</strong> platform.</p>
-<p>NOTE: This documentation is a work in progress.</p>
-<h2 id="table-of-contents">Table of contents</h2>
-<ul>
-<li><code>1.</code> <a href="introduction-to-atr">Introduction to ATR</a></li>
-<li><code>2.</code> <a href="user-guide">User guide</a></li>
-<li><code>3.</code> <a href="developer-guide">Developer guide</a>
-<ul>
-<li><code>3.1.</code> <a href="running-the-server">Running the server</a></li>
-<li><code>3.2.</code> <a href="overview-of-the-code">Overview of the code</a></li>
-<li><code>3.3.</code> <a href="database">Database</a></li>
-<li><code>3.4.</code> <a href="storage-interface">Storage interface</a></li>
-<li><code>3.5.</code> <a href="user-interface">User interface</a></li>
-<li><code>3.6.</code> <a href="tasks">Tasks</a></li>
-<li><code>3.7.</code> <a href="build-processes">Build processes</a></li>
-<li><code>3.8.</code> <a href="running-and-creating-tests">Running and creating tests</a></li>
-<li><code>3.9.</code> <a href="code-conventions">Code conventions</a></li>
-<li><code>3.10.</code> <a href="how-to-contribute">How to contribute</a></li>
-</ul>
-</li>
-</ul>
diff --git a/atr/docs/introduction-to-atr.html b/atr/docs/introduction-to-atr.html
deleted file mode 100644
index 2d0f316..0000000
--- a/atr/docs/introduction-to-atr.html
+++ /dev/null
@@ -1,27 +0,0 @@
-<h1 id="introduction-to-atr">1. Introduction to ATR</h1>
-<p><strong>Up</strong>: <a href=".">Documentation</a></p>
-<p><strong>Prev</strong>: (none)</p>
-<p><strong>Next</strong>: <code>2.</code> <a href="user-guide">User guide</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#what-is-atr">What is ATR?</a></li>
-<li><a href="#who-are-atr-users">Who are ATR users?</a></li>
-<li><a href="#what-is-atr-like-to-use">What is ATR like to use?</a></li>
-<li><a href="#who-develops-atr">Who develops ATR?</a></li>
-</ul>
-<h2 id="what-is-atr">What is ATR?</h2>
-<p>ATR is a platform through which committees of <a href="https://www.apache.org/">Apache Software Foundation</a> (ASF) projects can make official ASF software releases. Official ASF releases are endorsed as an "<a href="https://www.apache.org/legal/release-policy.html#release-definition">act of the Foundation</a>". It is therefore important that the foundation - its board, members, committees, and contributors - and the general public can have confidence in the releases.</p>
-<p>What sort of confidence in releases is required? All parties need to be certain that the software available for download is exactly that which was intended to be published by the applicable project management committee (PMC), and by the foundation. This may seem trivial, but software distribution platforms such as ATR now operate in extremely adversarial environments. In the years before ATR was launched, <a href="https://en.wikipedia.org/wiki/Supply_chain_attack">supply chain attacks [...]
-<p>The end goal of supply chain attacks is almost always to cause harm to users. Harms are wide-ranging and can include unwanted features, the extraction of money from the user, surveillance and exfiltration of data, and material damage. The exact methods of supply chain attacks vary, but the general principle is to modify some legitimate software between the time that it was written and the time that it was received by the end user, without the modification being noticed. If software is [...]
-<p><strong>The goal of ATR is to deter and minimize the risk of supply chain attacks.</strong> ATR does not ensure the quality of software received legitimately from PMCs. The foundation as a whole, of course, has the goal of establishing the highest quality of software to be produced, but that is not the responsibility of ATR as a platform. The responsibility of ATR is to ensure that the software it distributes to end users is the legitimate submission of each of our constituent PMCs. I [...]
-<h2 id="who-are-atr-users">Who are ATR users?</h2>
-<p>There are two kinds of ATR user: our participants who use ATR to publish their software, and ASF software end users who use ATR to obtain that software. This guide is primarily written for the former, our participants who are publishing their software. Skilled end users may be interested in reading this guide for the purpose of learning the purported security claims that we make, reviewing the implementation strategies that we picked to achieve them, and ascertaining the likelihood th [...]
-<p>It is important to remember that security is a complex and rapidly evolving field, as the parties are involved in an ongoing game of cat and mouse. Software producers are often under tight budget and time constraints, forced to prioritize properties other than security, working in environments known to be insecure, using practices known to be suboptimal, and deploying to architectures with known vulnerabilities. Attackers race to find mistakes before producers, and use them to their o [...]
-<p>In this guide, we document how ATR is situated in this complex security landscape. But we also document the day-to-day operation of ATR: which forms to use, which buttons to press, how to make the release process simple, convenient, and well understood, but always with the goal of producing software as it was intended to be.</p>
-<h2 id="what-is-atr-like-to-use">What is ATR like to use?</h2>
-<p>Security of ASF release processes is the primary goal of ATR, but outstanding usability is also necessary to achieve this goal. The ASF has been in operation since 1999, and has needed release procedures from the very start. ATR is the next step in the evolution of those procedures, but the release managers (RMs) responsible for releasing ASF software are accustomed to the existing procedures. Convenience is a visceral property with a disproportionate effect. If ATR were secure but le [...]
-<p>As such, we offer a choice of interfaces when using ATR. We have a web-based interface, a JSON API, and a command-line interface (CLI). We try to make functionality as available as possible across all three interfaces. We also plan to add a text user interface (TUI), which is a kind of hybrid of the web-based interface and the CLI. The intention of having so many interfaces is that users can choose the ones which are most convenient for them at each step.</p>
-<p>Speaking of steps, what are the steps to release software on ATR? We have kept this as simple as possible. First, the project's participants compose a candidate release from existing files. Second, as per ASF policy, the PMC votes on that candidate release. Third, if the vote passes, the PMC officially publishes and announces the erstwhile candidate release as a finished, official release. That's the whole process for the majority of PMCs, but of course there are many details and cons [...]
-<h2 id="who-develops-atr">Who develops ATR?</h2>
-<p>ATR is developed by ASF Tooling, an ASF initiative launched in 2025, and responsible for streamlining development, automating repetitive tasks, reducing technical debt, and enhancing collaboration throughout the ASF. The source code of ATR is developed in public as open source code, and ASF Tooling welcomes high quality contributions to the codebase from external contributors, whether from existing ASF contributors or members of the public. Because of the stringent security and usabil [...]
-<p>This manual is an integral part of ATR, and contributions to this manual are therefore treated like any of the rest of the code. We welcome all types of contribution, whether that be writing entire pages or correcting small typographical errors. The easiest path to contribution is to <a href="https://github.com/apache/tooling-trusted-releases/compare">create a pull request</a> on <a href="https://github.com/apache/tooling-trusted-releases">our GitHub repository</a>. You can also <a hr [...]
diff --git a/atr/docs/overview-of-the-code.html b/atr/docs/overview-of-the-code.html
deleted file mode 100644
index d785866..0000000
--- a/atr/docs/overview-of-the-code.html
+++ /dev/null
@@ -1,46 +0,0 @@
-<h1 id="overview-of-the-code">3.2. Overview of the code</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.1.</code> <a href="running-the-server">Running the server</a></p>
-<p><strong>Next</strong>: <code>3.3.</code> <a href="database">Database</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-<li><a href="#hypercorn-and-asgi">Hypercorn and ASGI</a></li>
-<li><a href="#routes-and-database">Routes and database</a></li>
-<li><a href="#user-interface">User interface</a></li>
-<li><a href="#scheduling-and-tasks">Scheduling and tasks</a></li>
-<li><a href="#api">API</a></li>
-<li><a href="#other-important-interfaces">Other important interfaces</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>This page is a high level view of the ATR code. References to symbols in this section are given without their <code>atr.</code> prefix, for brevity, and are linked to the respective source code. You should understand e.g. <a href="/ref/atr/server.py:app"><code>server.app</code></a> to mean <code>atr.server.app</code>.</p>
-<h2 id="hypercorn-and-asgi">Hypercorn and ASGI</h2>
-<p>ATR is an <a href="https://github.com/apache/infrastructure-asfquart">ASFQuart</a> application, running in <a href="https://hypercorn.readthedocs.io/en/latest/index.html">Hypercorn</a>. The entry point for Hypercorn is <a href="/ref/atr/server.py:app"><code>server.app</code></a>, which is then called with a few standard arguments <a href="https://asgi.readthedocs.io/en/latest/specs/main.html#overview">as per the ASGI specification</a>. We create the <code>app</code> object using the f [...]
-<pre><code class="language-python">app = create_app(config.get())
-</code></pre>
-<p>The <a href="/ref/atr/server.py:create_app"><code>server.create_app</code></a> function performs a lot of setup, and if you're interested in how the server works then you can read it and the functions it calls to understand the process further. In general, however, when developing ATR we do not make modifications at the ASFQuart, Quart, and Hypercorn levels very often.</p>
-<h2 id="routes-and-database">Routes and database</h2>
-<p>Users request ATR pages over HTTPS, and the ATR server processes those requests in route handlers. Most of those handlers are in <a href="/ref/atr/get/"><code>get</code></a> and <a href="/ref/atr/post/"><code>post</code></a>, with some helper code in <a href="/ref/atr/shared/"><code>shared</code></a>. What each handler does varies, of course, from handler to handler, but most perform at least one access to the ATR SQLite database.</p>
-<p>The path of the SQLite database is configured in <a href="/ref/atr/config.py:SQLITE_DB_PATH"><code>config.AppConfig.SQLITE_DB_PATH</code></a> by default, and will usually appear as <code>state/atr.db</code> with related <code>shm</code> and <code>wal</code> files. We do not expect ATR to have so many users that we need to scale beyond SQLite.</p>
-<p>We use <a href="https://sqlmodel.tiangolo.com/">SQLModel</a>, an ORM utilising <a href="https://docs.pydantic.dev/latest/">Pydantic</a> and <a href="https://www.sqlalchemy.org/">SQLAlchemy</a>, to create Python models for the ATR database. The core models file is <a href="/ref/atr/models/sql.py"><code>models.sql</code></a>. The most important individual SQLite models in this module are <a href="/ref/atr/models/sql.py:Committee"><code>Committee</code></a>, <a href="/ref/atr/models/sql. [...]
-<p>It is technically possible to interact with SQLite directly, but we do not do that in the ATR source. We use various interfaces in <a href="/ref/atr/db/__init__.py"><code>db</code></a> for reads, and interfaces in <a href="/ref/atr/storage/"><code>storage</code></a> for writes. We plan to move the <code>db</code> code into <code>storage</code> too eventually, because <code>storage</code> is designed to have read components and write components. There is also a legacy <a href="/ref/atr [...]
-<p>These interfaces, including route handlers in <a href="/ref/atr/get/"><code>get</code></a>, <a href="/ref/atr/post/"><code>post</code></a>, and <a href="/ref/atr/shared/"><code>shared</code></a>, along with <a href="/ref/atr/models/sql.py"><code>models.sql</code></a> and <a href="/ref/atr/storage/"><code>storage</code></a>, are where the majority of activity happens when developing ATR.</p>
-<h2 id="user-interface">User interface</h2>
-<p>ATR provides a web interface for users to interact with the platform, and the implementation of that interface is split across several modules. The web interface uses server-side rendering almost entirely, where HTML is generated on the server and sent to the browser.</p>
-<p>The template system in ATR is <a href="https://jinja.palletsprojects.com/">Jinja2</a>, always accessed through the ATR <a href="/ref/atr/template.py"><code>template</code></a> module. Template files in Jinja2 syntax are stored in <a href="/ref/atr/templates/"><code>templates/</code></a>, and route handlers render them using the asynchronous <a href="/ref/atr/template.py:render"><code>template.render</code></a> function.</p>
-<p>Template rendering can be slow if templates are loaded from disk on every request. To address this, we use <a href="/ref/atr/preload.py"><code>preload</code></a> to load all templates into memory before the server starts serving requests. The <a href="/ref/atr/preload.py:setup_template_preloading"><code>preload.setup_template_preloading</code></a> function registers a startup hook that finds and caches every template file.</p>
-<p>The ATR user interface includes many HTML forms. We use <a href="https://docs.pydantic.dev/latest/">Pydantic</a> for form handling, accessed through the ATR <a href="/ref/atr/form.py"><code>form</code></a> module. The <a href="/ref/atr/form.py:Form"><code>form.Form</code></a> base class extends <code>pydantic.BaseModel</code> to provide form-specific functionality. Each form field is defined using Pydantic type annotations along with the <a href="/ref/atr/form.py:label"><code>form.lab [...]
-<p>In addition to templates, we sometimes need to generate HTML programmatically in Python. For this we use <a href="https://htpy.dev/">htpy</a>, another third party library, for building HTML using Python syntax. The ATR <a href="/ref/atr/htm.py"><code>htm</code></a> module extends htpy with a <a href="/ref/atr/htm.py:Block"><code>Block</code></a> class that makes it easier to build complex HTML structures incrementally. Using htpy means that we get type checking for our HTML generation [...]
-<p>Refer to the <a href="user-interface">full user interface development guide</a> for more information about this topic.</p>
-<h2 id="scheduling-and-tasks">Scheduling and tasks</h2>
-<p>Many operations in ATR are too slow to run during an HTTP request, so we run them asynchronously in background worker processes. The task scheduling system in ATR is built from three components: a task queue stored in the SQLite database, a worker manager that spawns and monitors worker processes, and the worker processes themselves that claim and execute tasks.</p>
-<p>The task queue is stored in a table defined by the <a href="/ref/atr/models/sql.py:Task"><code>Task</code></a> model in <a href="/ref/atr/models/sql.py"><code>models.sql</code></a>. Each task has a status, a type, arguments encoded as JSON, and metadata such as when it was added and which user created it. When route handlers need to perform slow operations, they create a new <code>Task</code> row with status <code>QUEUED</code> and commit it to the database.</p>
-<p>The ATR <a href="/ref/atr/manager.py"><code>manager</code></a> module provides the <a href="/ref/atr/manager.py:WorkerManager"><code>WorkerManager</code></a> class, which maintains a pool of worker processes. When the ATR server starts, the manager spawns a configurable number of worker processes and monitors them continuously. The manager checks every few seconds whether workers are still running, whether any tasks have exceeded their time limits, and whether the worker pool needs to [...]
-<p>The ATR <a href="/ref/atr/worker.py"><code>worker</code></a> module implements the workers. Each worker process runs in a loop. It claims the oldest queued task from the database, executes it, records the result, and then claims the next task atomically using an <code>UPDATE ... WHERE</code> statement. After a worker has processed a fixed number of tasks, it exits voluntarily to help to avoid memory leaks. The manager then spawns a fresh worker to replace it. Task execution happens in [...]
-<p>Tasks themselves are defined in the ATR <a href="/ref/atr/tasks/"><code>tasks</code></a> directory. The <a href="/ref/atr/tasks/__init__.py"><code>tasks</code></a> module contains functions for queueing tasks and resolving task types to their handler functions. Task types include operations such as importing keys, generating SBOMs, sending messages, and importing files from SVN. The most common category of task is automated checks on release artifacts. These checks are implemented in  [...]
-<h2 id="api">API</h2>
-<p>The ATR API provides programmatic access to most ATR functionality. API endpoints are defined in <a href="/ref/atr/api/__init__.py"><code>api</code></a>, and their URL paths are prefixed with <code>/api/</code>. The API uses <a href="https://www.openapis.org/">OpenAPI</a> for documentation, which is automatically generated from the endpoint definitions and served at <code>/api/docs</code>. Users send requests with a <a href="https://en.wikipedia.org/wiki/JSON_Web_Token">JWT</a> create [...]
-<p>API request and response models are defined in <a href="/ref/atr/models/api.py"><code>models.api</code></a> using Pydantic. Each endpoint has an associated request model that validates incoming data, and a response model that validates outgoing data. The API returns JSON in all cases, with appropriate HTTP status codes.</p>
-<h2 id="other-important-interfaces">Other important interfaces</h2>
-<p>ATR uses ASF OAuth for user login, and then determines what actions each user can perform based on their committee memberships. The ATR <a href="/ref/atr/principal.py"><code>principal</code></a> module handles authorization by checking whether users are members of relevant committees. It queries and caches LDAP to get committee membership information. The <a href="/ref/atr/principal.py:Authorisation"><code>Authorisation</code></a> class provides methods to check whether a user is a me [...]
-<p>The server configuration in <a href="/ref/atr/config.py"><code>config</code></a> determines a lot of global state, and the <a href="/ref/atr/util.py"><code>util</code></a> module contains lots of useful code which is used throughout ATR.</p>
diff --git a/atr/docs/running-and-creating-tests.html b/atr/docs/running-and-creating-tests.html
deleted file mode 100644
index c957c65..0000000
--- a/atr/docs/running-and-creating-tests.html
+++ /dev/null
@@ -1,36 +0,0 @@
-<h1 id="running-and-creating-tests">3.8. Running and creating tests</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.7.</code> <a href="build-processes">Build processes</a></p>
-<p><strong>Next</strong>: <code>3.9.</code> <a href="code-conventions">Code conventions</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#running-tests">Running tests</a></li>
-<li><a href="#creating-tests">Creating tests</a></li>
-</ul>
-<h2 id="running-tests">Running tests</h2>
-<p>We currently only have end-to-end browser tests, but we plan to expand these as part of <a href="https://github.com/apache/tooling-trusted-releases/issues/209">Issue #209</a>. Meanwhile, these browser tests serve as a simple consistency check when developing ATR.</p>
-<p>To run the tests, you will need Docker. Other OCI runtimes should work, but you will need to edit the test scripts accordingly.</p>
-<h3 id="using-docker-compose">Using Docker Compose</h3>
-<p>The simplest way to run the tests is using Docker Compose, which starts both ATR and the Playwright test container:</p>
-<pre><code class="language-shell">sh tests/run-tests.sh
-</code></pre>
-<p>This uses <a href="/ref/tests/docker-compose.yml"><code>tests/docker-compose.yml</code></a> to orchestrate the test environment. The ATR server runs in one container and the Playwright tests run in another, connected via a Docker network. These tests are automatically run in our GitHub CI as part of <a href="/ref/.github/workflows/build.yml"><code>.github/workflows/build.yml</code></a>.</p>
-<h3 id="using-host-networking">Using host networking</h3>
-<p>If you already have ATR running locally with <code>make serve-local</code>, you can run the Playwright tests directly against it instead of using Docker Compose:</p>
-<pre><code class="language-shell">make build-playwright &amp;&amp; make run-playwright
-</code></pre>
-<p>Where the two <code>make</code> invocations correspond to:</p>
-<pre><code class="language-shell">docker build -t atr-playwright -f tests/Dockerfile.playwright playwright
-docker run --net=host -it atr-playwright python3 test.py --skip-slow
-</code></pre>
-<p>In other words, we build <a href="/ref/tests/Dockerfile.playwright"><code>tests/Dockerfile.playwright</code></a>, and then run <a href="/ref/playwright/test.py"><code>playwright/test.py</code></a> inside that container using host networking to access your locally running ATR instance. Replace <code>docker</code> with the name of your Docker-compatible OCI runtime to use an alternative runtime.</p>
-<h3 id="test-duration">Test duration</h3>
-<p>The tests should, as of 14 Oct 2025, take about 40 to 50 seconds to run in Docker Compose, and 20 to 25 seconds to run on the host. The last line of the test output should be <code>Tests finished successfully</code>, and if the tests do not complete successfully there should be an obvious Python backtrace.</p>
-<h2 id="creating-tests">Creating tests</h2>
-<p>You can add tests to <code>playwright/test.py</code>. If you're feeling particularly adventurous, you can add separate unit tests etc., but it's okay to add tests only to the Playwright test script until <a href="https://github.com/apache/tooling-trusted-releases/issues/209">Issue #209</a> is resolved.</p>
-<h3 id="how-the-tests-work">How the tests work</h3>
-<p>The browser tests use <a href="https://playwright.dev/">Playwright</a>, which is a cross-browser, cross-platform web testing framework. It's a bit like the older <a href="https://en.wikipedia.org/wiki/PhantomJS">PhantomJS</a>, now discontinued, which allows you to operate a browser through scripting. Playwright took the same concept and improved the user experience by adding better methods for polling browser state. Most interactions with a browser take some time to complete, and in P [...]
-<p>We use the official Playwright OCI container, install a few dependencies (<code>apt-get</code> is available in the container), and then run <code>test.py</code>.</p>
-<p>The <code>test.py</code> script calls <a href="/ref/playwright/test.py:run_tests"><code>run_tests</code></a> from its <code>main</code>, which sets up all the context, but the main action takes place in <a href="/ref/playwright/test.py:test_all"><code>test_all</code></a>. This function removes any state accidentally left over from a previous run, then runs tests of certain components. Because ATR is stateful, the order of the tests is important. When adding a test, please be careful t [...]
-<p>We want to make it more clear which Playwright tests depend on which, and have more isolated tests. Reusing context, however, helps to speed up the tests.</p>
-<p>The actual test cases themselves tend to use helpers such as <a href="/ref/playwright/test.py:go_to_path"><code>go_to_path</code></a> and <a href="/ref/playwright/test.py:wait_for_path"><code>wait_for_path</code></a>, and then call <a href="https://docs.python.org/3/library/logging.html#logging.info"><code>logging.info</code></a> to print information to the console. Try to keep logging messages terse and informative.</p>
diff --git a/atr/docs/running-the-server.html b/atr/docs/running-the-server.html
deleted file mode 100644
index 8f5762b..0000000
--- a/atr/docs/running-the-server.html
+++ /dev/null
@@ -1,55 +0,0 @@
-<h1 id="running-the-server">3.1. Running the server</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: (none)</p>
-<p><strong>Next</strong>: <code>3.2.</code> <a href="overview-of-the-code">Overview of the code</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-<li><a href="#get-the-source">Get the source</a></li>
-<li><a href="#install-dependencies">Install dependencies</a></li>
-<li><a href="#run-the-server">Run the server</a></li>
-<li><a href="#load-the-site">Load the site</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>To develop ATR locally, we manage dependencies using <a href="https://docs.astral.sh/uv/">uv</a>. To run ATR on ASF hardware, we run it in containers managed by Puppet, but since this guide is about development, we focus on using uv.</p>
-<h2 id="get-the-source">Get the source</h2>
-<p><a href="https://github.com/apache/tooling-trusted-releases/fork">Fork the source code</a> of <a href="https://github.com/apache/tooling-trusted-releases">ATR on GitHub</a>, and then <a href="https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository">clone your fork locally</a>.</p>
-<p>There are lots of files and directories in the root of the ATR Git repository. The most important thing to know is that <code>atr/</code> contains the source code. ATR is a Python application based on <a href="https://github.com/apache/infrastructure-asfquart">ASFQuart</a>, which is based on <a href="https://github.com/pallets/quart">Quart</a>. The Quart web framework is an asynchronous version of <a href="https://github.com/pallets/flask">Flask</a>, a very widely used synchronous web [...]
-<h2 id="install-dependencies">Install dependencies</h2>
-<p>To run ATR locally after cloning the source, you will need to install the following dependencies:</p>
-<ul>
-<li><a href="https://github.com/commonmark/cmark">cmark</a> (optional; for rebuilding documentation)</li>
-<li>Any <a href="https://en.wikipedia.org/wiki/POSIX">POSIX</a> compliant <a href="https://frippery.org/make/">make</a></li>
-<li><a href="https://github.com/FiloSottile/mkcert">mkcert</a></li>
-<li><a href="https://www.python.org/downloads/release/python-3138/">Python 3.13</a></li>
-<li><a href="https://docs.astral.sh/uv/#installation">uv</a></li>
-</ul>
-<p>You can install Python 3.13 through your package manager or through uv. Here is how to install these dependencies on <a href="https://en.wikipedia.org/wiki/Alpine_Linux">Alpine Linux</a>:</p>
-<pre><code class="language-shell">apk add cmark curl git make mkcert@testing
-curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh
-uv python install 3.13
-</code></pre>
-<p>For macOS these instructions become:</p>
-<pre><code class="language-shell">brew install cmark mkcert
-curl -LsSf https://astral.sh/uv/install.sh | sh
-rehash
-uv python install 3.13
-</code></pre>
-<p>ATR should work in any POSIX style environment.</p>
-<h2 id="run-the-server">Run the server</h2>
-<p>Then, to run the server:</p>
-<pre><code class="language-shell">cd tooling-trusted-releases/
-mkdir state
-make certs-local
-make serve-local
-</code></pre>
-<p>The <code>certs-local</code> step runs <code>mkcert localhost.apache.org localhost 127.0.0.1 ::1</code> to generate a locally trusted TLS certificate. If the certificate is not trusted, you may have to follow the <a href="https://github.com/FiloSottile/mkcert/blob/master/README.md">mkcert guide</a> to resolve the issue.</p>
-<p>ATR requires TLS even for development because login is performed through the actual ASF OAuth server. This way, the development behavior aligns closely with the production behavior. We try to minimize differences between development and production environments.</p>
-<h2 id="load-the-site">Load the site</h2>
-<p>ATR will then be served on various hosts, but we recommend using only <code>localhost.apache.org</code>. This requires adding an entry to your <code>/etc/hosts</code> and potentially restarting your DNS server. If you do this, the following link should work:</p>
-<p><a href="https://localhost.apache.org:8080/"><code>https://localhost.apache.org:8080/</code></a></p>
-<p>If you do not want to change your <code>/etc/hosts</code>, you can use <code>127.0.0.1</code>. You should not use <code>localhost</code>. The following link should work:</p>
-<p><a href="https://127.0.0.1:8080/"><code>https://127.0.0.1:8080/</code></a></p>
-<p>Pick one or the other, because logging into the site on one host does not log you in to the site on any other host.</p>
-<p>It will take one or two minutes for the server to fetch committee and project information from the ASF website. Until the fetch is complete, no existing committees and projects will show.</p>
-<p>Developers without LDAP credentials will be unable to perform <code>rsync</code> writes and certain tasks may also fail. To enable these actions to succeed, visit <code>/user/cache</code> and press the "Cache me!" button. This writes your session information to the ATR state directory, where it will be consulted instead of an LDAP lookup if it exists. The same page also allows you to clear your session cache data. When you clear your session cache data, the <code>atr/principal.py</cod [...]
diff --git a/atr/docs/storage-interface.html b/atr/docs/storage-interface.html
deleted file mode 100644
index af3c8df..0000000
--- a/atr/docs/storage-interface.html
+++ /dev/null
@@ -1,100 +0,0 @@
-<h1 id="storage-interface">3.4. Storage interface</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.3.</code> <a href="database">Database</a></p>
-<p><strong>Next</strong>: <code>3.5.</code> <a href="user-interface">User interface</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-<li><a href="#how-do-we-read-from-storage">How do we read from storage?</a></li>
-<li><a href="#how-do-we-write-to-storage">How do we write to storage?</a></li>
-<li><a href="#how-do-we-add-new-storage-functionality">How do we add new storage functionality?</a></li>
-<li><a href="#how-do-we-use-outcomes">How do we use outcomes?</a></li>
-<li><a href="#what-about-audit-logging">What about audit logging?</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>All database writes, and some reads, in ATR go through the <a href="/ref/atr/storage/__init__.py"><code>storage</code></a> interface. This interface <strong>enforces permissions</strong>, <strong>centralizes audit logging</strong>, and <strong>provides type-safe access</strong> to the database. In other words, avoid calling <a href="/ref/atr/db/__init__.py"><code>db</code></a> directly in route handlers if possible.</p>
-<p>The storage interface recognizes several permission levels: general public (unauthenticated visitors), foundation committer (any ASF account), committee participant (committers and PMC members), committee member (PMC members only), and foundation admin (infrastructure administrators). Each level inherits from the previous one, so for example committee members can do everything committee participants can do, plus additional operations.</p>
-<p>The storage interface does not make it impossible to bypass authorization, because you can always import <code>db</code> directly and write to the database. But it makes bypassing authorization an explicit choice that requires deliberate action, and it makes the safer path the easier path. This is a pragmatic approach to security: we cannot prevent all mistakes, but we can make it harder to make them accidentally.</p>
-<h2 id="how-do-we-read-from-storage">How do we read from storage?</h2>
-<p>Reading from storage is a work in progress. There are some existing methods, but most of the functionality is currently in <code>db</code> or <code>db.interaction</code>, and much work is required to migrate this to the storage interface. We have given this less priority because reads are generally safe, with the exception of a few components such as user tokens, which should be given greater migration priority.</p>
-<h2 id="how-do-we-write-to-storage">How do we write to storage?</h2>
-<p>To write to storage we open a write session, request specific permissions, use the exposed functionality, and then handle the outcome. Here is an actual example from <a href="/ref/atr/post/start.py"><code>post/start.py</code></a>:</p>
-<pre><code class="language-python">async with storage.write(session) as write:
-    wacp = await write.as_project_committee_participant(project_name)
-    new_release, _project = await wacp.release.start(project_name, version)
-</code></pre>
-<p>The <code>wacp</code> object, short for <code>w</code>rite <code>a</code>s <code>c</code>ommittee <code>p</code>articipant, provides access to domain-specific writers: <code>announce</code>, <code>checks</code>, <code>distributions</code>, <code>keys</code>, <code>policy</code>, <code>project</code>, <code>release</code>, <code>sbom</code>, <code>ssh</code>, <code>tokens</code>, and <code>vote</code>.</p>
-<p>The write session takes an optional <a href="/ref/atr/web.py:Committer"><code>Committer</code></a> or ASF UID, typically <code>session.uid</code> from the logged-in user. If you omit the UID, the session determines it automatically from the current request context. The write object checks LDAP memberships and raises <a href="/ref/atr/storage/__init__.py:AccessError"><code>storage.AccessError</code></a> if the user is not authorized for the requested permission level.</p>
-<p>Because projects belong to committees, we provide <a href="/ref/atr/storage/__init__.py:as_project_committee_member"><code>write.as_project_committee_member(project_name)</code></a> and <a href="/ref/atr/storage/__init__.py:as_project_committee_participant"><code>write.as_project_committee_participant(project_name)</code></a>, which look up the project's committee and authenticate the user as a member or participant of that committee. This is convenient when, for example, the URL prov [...]
-<p>Here is a more complete example from <a href="/ref/atr/api/__init__.py"><code>api/__init__.py</code></a> that shows the classic three step pattern:</p>
-<pre><code class="language-python">async with storage.write(asf_uid) as write:
-    # 1. Request permissions
-    wafc = write.as_foundation_committer()
-
-    # 2. Use the exposed functionality
-    outcome = await wafc.keys.ensure_stored_one(data.key)
-
-    # 3. Handle the outcome
-    key = outcome.result_or_raise()
-</code></pre>
-<p>In this case we decide to raise as soon as there is any error. We could also choose to display a warning, ignore the error, collect multiple outcomes for batch processing, or handle it in any other way appropriate for the situation.</p>
-<h2 id="how-do-we-add-new-storage-functionality">How do we add new storage functionality?</h2>
-<p>Add methods to classes in the <a href="/ref/atr/storage/writers/"><code>storage/writers</code></a> or <a href="/ref/atr/storage/readers/"><code>storage/readers</code></a> directories. Code to perform any action associated with public keys that involves writing to storage, for example, goes in <a href="/ref/atr/storage/writers/keys.py"><code>storage/writers/keys.py</code></a>.</p>
-<p>Classes in writer and reader modules must be named to match the permission hierarchy:</p>
-<pre><code class="language-python">class GeneralPublic:
-    def __init__(
-        self,
-        write: storage.Write,
-        write_as: storage.WriteAsGeneralPublic,
-        data: db.Session,
-    ) -&gt; None:
-        self.__write = write
-        self.__write_as = write_as
-        self.__data = data
-
-class FoundationCommitter(GeneralPublic):
-    def __init__(
-        self,
-        write: storage.Write,
-        write_as: storage.WriteAsFoundationCommitter,
-        data: db.Session
-    ) -&gt; None:
-        super().__init__(write, write_as, data)
-        self.__write = write
-        self.__write_as = write_as
-        self.__data = data
-
-class CommitteeParticipant(FoundationCommitter):
-    def __init__(
-        self,
-        write: storage.Write,
-        write_as: storage.WriteAsCommitteeParticipant,
-        data: db.Session,
-        committee_name: str,
-    ) -&gt; None:
-        super().__init__(write, write_as, data)
-        self.__committee_name = committee_name
-
-class CommitteeMember(CommitteeParticipant):
-    ...
-</code></pre>
-<p>This hierarchy that this creates is: <code>GeneralPublic</code> → <code>FoundationCommitter</code> → <code>CommitteeParticipant</code> → <code>CommitteeMember</code>. You can add methods at any level. A method on <code>CommitteeMember</code> is only available to committee members, while a method on <code>FoundationCommitter</code> is available to everyone who has logged in.</p>
-<p>Use <code>__private_methods</code> for helper code that is not part of the public interface. Use <code>public_methods</code> for operations that should be available to callers at the appropriate permission level. Consider returning <a href="/ref/atr/storage/outcome.py:Outcome"><code>Outcome</code></a> types to allow callers flexibility in error handling. Refer to the <a href="#how-do-we-use-outcomes">section on using outcomes</a> for more details.</p>
-<p>After adding a new writer module, register it in the appropriate <code>WriteAs*</code> classes in <a href="/ref/atr/storage/__init__.py"><code>storage/__init__.py</code></a>. For example, when adding the <code>distributions</code> writer, it was necessary to add <code>self.distributions = writers.distributions.CommitteeMember(write, self, data, committee_name)</code> to the <a href="/ref/atr/storage/__init__.py:WriteAsCommitteeMember"><code>WriteAsCommitteeMember</code></a> class.</p>
-<h2 id="how-do-we-use-outcomes">How do we use outcomes?</h2>
-<p>Consider using <strong>outcome types</strong> from <a href="/ref/atr/storage/outcome.py"><code>storage.outcome</code></a> when returning results from writer methods. Outcomes let you represent both success and failure without raising exceptions, which gives callers flexibility in how they handle errors.</p>
-<p>An <a href="/ref/atr/storage/outcome.py:Outcome"><code>Outcome[T]</code></a> is either a <a href="/ref/atr/storage/outcome.py:Result"><code>Result[T]</code></a> wrapping a successful value, or an <a href="/ref/atr/storage/outcome.py:Error"><code>Error[T]</code></a> wrapping an exception. You can check which it is with the <code>ok</code> property or pattern matching, extract the value with <code>result_or_raise()</code>, or extract the error with <code>error_or_raise()</code>.</p>
-<p>Here is an example from <a href="/ref/atr/post/keys.py"><code>post/keys.py</code></a> that processes multiple keys and collects outcomes:</p>
-<pre><code class="language-python">async with storage.write() as write:
-    wacm = write.as_committee_member(selected_committee)
-    outcomes = await wacm.keys.ensure_associated(keys_text)
-
-success_count = outcomes.result_count
-error_count = outcomes.error_count
-</code></pre>
-<p>The <code>ensure_associated</code> method returns an <a href="/ref/atr/storage/outcome.py:List"><code>outcome.List</code></a>, which is a collection of outcomes. Some keys might import successfully, and others might fail because they are malformed or already exist. The caller can inspect the list to see how many succeeded and how many failed, and present that information to the user.</p>
-<p>The <code>outcome.List</code> class provides many useful methods: <a href="/ref/atr/storage/outcome.py:results"><code>results()</code></a> to get only the successful values, <a href="/ref/atr/storage/outcome.py:errors"><code>errors()</code></a> to get only the exceptions, <a href="/ref/atr/storage/outcome.py:result_count"><code>result_count</code></a> and <a href="/ref/atr/storage/outcome.py:error_count"><code>error_count</code></a> to count them, and <a href="/ref/atr/storage/outcome [...]
-<p>Use outcomes when an operation might fail for some items but succeed for others, or when you want to give the caller control over error handling. Do not use them when failure should always raise an exception, such as authorization failures or database connection errors. Those should be raised immediately.</p>
-<h2 id="what-about-audit-logging">What about audit logging?</h2>
-<p>Storage write operations can be logged to <a href="/ref/atr/config.py:STORAGE_AUDIT_LOG_FILE"><code>config.AppConfig.STORAGE_AUDIT_LOG_FILE</code></a>, which is <code>state/storage-audit.log</code> by default. Each log entry is a JSON object containing the timestamp, the action name, and relevant parameters. When you write a storage method that should be audited, call <code>self.__write_as.append_to_audit_log(**kwargs)</code> with whatever parameters are relevant to that specific oper [...]
-<p>Audit logging must be done manually because the values to log are often those computed during method execution, not just those passed as arguments which could be logged automatically. When deleting a release, for example, we log <code>asf_uid</code> (instance attribute), <code>project_name</code> (argument), and <code>version</code> (argument), but when issuing a JWT from a PAT, we log <code>asf_uid</code> (instance attribute) and <code>pat_hash</code> (<em>computed</em>). Each operat [...]
diff --git a/atr/docs/tasks.html b/atr/docs/tasks.html
deleted file mode 100644
index 518aa8e..0000000
--- a/atr/docs/tasks.html
+++ /dev/null
@@ -1,53 +0,0 @@
-<h1 id="tasks">3.6. Tasks</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.5.</code> <a href="user-interface">User interface</a></p>
-<p><strong>Next</strong>: <code>3.7.</code> <a href="build-processes">Build processes</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-<li><a href="#checks">Checks</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>Tasks are computations run in the background in dedicated worker processes orchestrated by a manager.</p>
-<h2 id="checks">Checks</h2>
-<p>One important subset of task in ATR is the check. Checks are run when a release manager adds or modifies files in a release candidate draft. The outputs of the checks alert the release manager to potential issues.</p>
-<p>There are several checks for correctness that are already built out, and this how-to provides pointers for developers wishing to add new checks for relevant pieces of a release. Currently as of <code>alpha-2</code> ATR has checks for the following:</p>
-<ol>
-<li>Correct hashing (<code>sql.TaskType.HASHING_CHECK</code>, <code>hashing.check</code>)</li>
-<li>Compliant license (<code>sql.TaskType.LICENSE_FILES</code>, <code>license.files</code>)</li>
-<li>Compliant license headers (<code>sql.TaskType.LICENSE_HEADERS</code>, <code>license.headers</code>)</li>
-<li>File paths (<code>sql.TaskType.PATHS_CHECK</code>, <code>paths.check</code>)</li>
-<li>RAT results (<code>sql.TaskType.RAT_CHECK</code>, <code>rat.check</code>)</li>
-<li>Correct signature (<code>sql.TaskType.SIGNATURE_CHECK</code>, <code>signature.check</code>)</li>
-<li>Tarball integrity (<code>sql.TaskType.TARGZ_INTEGRITY</code>, <code>targz.integrity</code>)</li>
-<li>Tarball structure (<code>sql.TaskType.TARGZ_STRUCTURE</code>, <code>targz.structure</code>)</li>
-<li>Zip file integrity (<code>sql.TaskType.ZIPFORMAT_INTEGRITY</code>, <code>zipformat.integrity</code>)</li>
-<li>Zip file structure (<code>sql.TaskType.ZIPFORMAT_STRUCTURE</code>, <code>zipformat.structure</code>)</li>
-</ol>
-<h3 id="adding-a-task-check-module">Adding a task check module</h3>
-<p>In <code>atr/tasks/checks</code> you will find several modules that perform these check tasks, including <code>hashing.py</code>, <code>license.py</code>, etc. To write a new check task, add a module here that performs the checks needed.</p>
-<h3 id="importing-and-using-a-check-module">Importing and using a check module</h3>
-<p>In <code>atr/tasks/__init__.py</code> you will see imports for existing modules where you can add an import for new check task, for example:</p>
-<pre><code class="language-python">import atr.tasks.checks.hashing as hashing
-import atr.tasks.checks.license as license
-</code></pre>
-<p>And in the <code>resolve</code> function you will see where those modules are exercised where you can add a <code>case</code> statement for the new task:</p>
-<pre><code class="language-python">def resolve(task_type: sql.TaskType) -&gt; Callable[..., Awaitable[results.Results | None]]:  # noqa: C901
-    match task_type:
-        case sql.TaskType.HASHING_CHECK:
-            return hashing.check
-        case sql.TaskType.KEYS_IMPORT_FILE:
-            return keys.import_file
-        case sql.TaskType.LICENSE_FILES:
-            return license.files
-        case sql.TaskType.LICENSE_HEADERS:
-            return license.headers
-</code></pre>
-<h3 id="defining-a-task-type">Defining a task type</h3>
-<p>In <code>atr/models/sql.py</code> you will find the <code>TaskType</code> class where you can add a new mapping for the task:</p>
-<pre><code class="language-python">class TaskType(str, enum.Enum):
-    HASHING_CHECK = "hashing_check"
-    KEYS_IMPORT_FILE = "keys_import_file"
-    LICENSE_FILES = "license_files"
-    LICENSE_HEADERS = "license_headers"
-</code></pre>
diff --git a/atr/docs/user-guide.html b/atr/docs/user-guide.html
deleted file mode 100644
index f232dbc..0000000
--- a/atr/docs/user-guide.html
+++ /dev/null
@@ -1,10 +0,0 @@
-<h1 id="user-guide">2. User guide</h1>
-<p><strong>Up</strong>: <a href=".">Documentation</a></p>
-<p><strong>Prev</strong>: <code>1.</code> <a href="introduction-to-atr">Introduction to ATR</a></p>
-<p><strong>Next</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>This is a work in progress. Meanwhile, you can read the <a href="/tutorial">ATR tutorial</a>.</p>
diff --git a/atr/docs/user-interface.html b/atr/docs/user-interface.html
deleted file mode 100644
index cf4527c..0000000
--- a/atr/docs/user-interface.html
+++ /dev/null
@@ -1,218 +0,0 @@
-<h1 id="user-interface">3.5. User interface</h1>
-<p><strong>Up</strong>: <code>3.</code> <a href="developer-guide">Developer guide</a></p>
-<p><strong>Prev</strong>: <code>3.4.</code> <a href="storage-interface">Storage interface</a></p>
-<p><strong>Next</strong>: <code>3.6.</code> <a href="tasks">Tasks</a></p>
-<p><strong>Sections</strong>:</p>
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-<li><a href="#jinja2-templates">Jinja2 templates</a></li>
-<li><a href="#forms">Forms</a></li>
-<li><a href="#programmatic-html">Programmatic HTML</a></li>
-<li><a href="#the-htmblock-class">The htm.Block class</a></li>
-<li><a href="#how-a-route-renders-ui">How a route renders UI</a></li>
-</ul>
-<h2 id="introduction">Introduction</h2>
-<p>ATR uses server-side rendering almost exclusively: the server generates HTML and sends it to the browser, which displays it. We try to avoid client-side scripting, and in the rare cases where we need dynamic front end components we use plain TypeScript without recourse to any third party framework. (We have some JavaScript too, but we aim to use TypeScript only.) Sometimes we incur a full page load where perhaps it would be more ideal to update a fragment of the DOM in place, but page [...]
-<p>The UI is built from three main pieces: <a href="https://jinja.palletsprojects.com/">Jinja2</a> for templates, <a href="https://wtforms.readthedocs.io/">WTForms</a> for HTML forms, and <a href="https://htpy.dev/">htpy</a> for programmatic HTML generation. We style everything with <a href="https://getbootstrap.com/">Bootstrap</a>, which we customize slightly.</p>
-<h2 id="jinja2-templates">Jinja2 templates</h2>
-<p>Templates live in <a href="/ref/atr/templates/"><code>templates/</code></a>. Each template is a Jinja2 file that defines HTML structure with placeholders for dynamic content. Route handlers render templates by calling <a href="/ref/atr/template.py:render"><code>template.render</code></a>, which is an alias for <a href="/ref/atr/template.py:render_sync"><code>template.render_sync</code></a>. The function is asynchronous and takes a template name plus keyword arguments for the template  [...]
-<p>Here is an example from <a href="/ref/atr/get/keys.py:add"><code>get/keys.py</code></a>:</p>
-<pre><code class="language-python">return await template.render(
-    "keys-add.html",
-    asf_id=session.uid,
-    user_committees=participant_of_committees,
-    form=form,
-    key_info=key_info,
-    algorithms=shared.algorithms,
-)
-</code></pre>
-<p>The template receives these variables and can access them directly. If you pass a variable called <code>form</code>, the template can use <code>{{ form }}</code> to render it. <a href="https://jinja.palletsprojects.com/en/stable/templates/#list-of-control-structures">Jinja2 has control structures</a> like <code>{% for %}</code> and <code>{% if %}</code>, which you use when iterating over data or conditionally showing content.</p>
-<p>Templates are loaded into memory at server startup by <a href="/ref/atr/preload.py:setup_template_preloading"><code>preload.setup_template_preloading</code></a>. This means that changing a template requires restarting the server in development, which can be configured to happen automatically, but it also means that rendering is fast because we never do a disk read during request handling. The preloading scans <a href="/ref/atr/templates/"><code>templates/</code></a> recursively and ca [...]
-<p>Template rendering happens in a thread pool to avoid blocking the async event loop. The function <a href="/ref/atr/template.py:_render_in_thread"><code>_render_in_thread</code></a> uses <code>asyncio.to_thread</code> to execute Jinja2's synchronous <code>render</code> method.</p>
-<h2 id="forms">Forms</h2>
-<p>HTML forms in ATR are handled by <a href="https://docs.pydantic.dev/latest/">Pydantic</a> models accessed through our <a href="/ref/atr/form.py"><code>form</code></a> module. Each form is a class that inherits from <a href="/ref/atr/form.py:Form"><code>form.Form</code></a>, which itself inherits from <code>pydantic.BaseModel</code>. Form fields are defined as class attributes using Pydantic type annotations, with the <a href="/ref/atr/form.py:label"><code>form.label</code></a> functio [...]
-<p>Here is a typical form definition from <a href="/ref/atr/shared/keys.py"><code>shared/keys.py</code></a>:</p>
-<pre><code class="language-python">class AddOpenPGPKeyForm(form.Form):
-    public_key: str = form.label(
-        "Public OpenPGP key",
-        'Your public key should be in ASCII-armored format, starting with "-----BEGIN PGP PUBLIC KEY BLOCK-----"',
-        widget=form.Widget.TEXTAREA,
-    )
-    selected_committees: form.StrList = form.label(
-        "Associate key with committees",
-        "Select the committees with which to associate your key.",
-    )
-
-    @pydantic.model_validator(mode="after")
-    def validate_at_least_one_committee(self) -&gt; "AddOpenPGPKeyForm":
-        if not self.selected_committees:
-            raise ValueError("You must select at least one committee to associate with this key")
-        return self
-</code></pre>
-<h3 id="field-types-and-labels">Field types and labels</h3>
-<p>The <a href="/ref/atr/form.py:label"><code>form.label</code></a> function is used to add metadata to Pydantic fields. The first argument is the label text, the second (optional) argument is documentation text that appears below the field, and you can pass additional keyword arguments like <code>widget=form.Widget.TEXTAREA</code> to specify the HTML widget type.</p>
-<p>Fields use Pydantic type annotations to define their data type:</p>
-<ul>
-<li><code>str</code> - text input (default widget: <code>Widget.TEXT</code>)</li>
-<li><code>form.Email</code> - email input with validation</li>
-<li><code>form.URL</code> - URL input with validation</li>
-<li><code>form.Bool</code> - checkbox</li>
-<li><code>form.Int</code> - number input</li>
-<li><code>form.StrList</code> - multiple checkboxes that collect strings</li>
-<li><code>form.File</code> - single file upload</li>
-<li><code>form.FileList</code> - multiple file upload</li>
-<li><code>form.Enum[EnumType]</code> - dropdown select from enum values</li>
-<li><code>form.Set[EnumType]</code> - multiple checkboxes from enum values</li>
-</ul>
-<p>Empty values for fields are allowed by default in most cases, but URL is an exception.</p>
-<p>The <code>widget</code> parameter in <a href="/ref/atr/form.py:label"><code>form.label</code></a> lets you override the default widget for a field type. Available widgets include: <code>TEXTAREA</code>, <code>CHECKBOXES</code>, <code>SELECT</code>, <code>RADIO</code>, <code>HIDDEN</code>, and others from the <code>form.Widget</code> enum. Common reasons to override:</p>
-<ul>
-<li>HIDDEN: for values passed from the route, not entered by the user</li>
-<li>TEXTAREA: for multi-line text input</li>
-<li>RADIO: for mutually exclusive choices</li>
-<li>CUSTOM: for fully custom rendering</li>
-</ul>
-<p>From <a href="/ref/atr/shared/projects.py:AddProjectForm"><code>projects.AddProjectForm</code></a>:</p>
-<pre><code class="language-python">committee_name: str = form.label("Committee name", widget=form.Widget.HIDDEN)
-</code></pre>
-<p>From <a href="/ref/atr/shared/resolve.py:SubmitForm"><code>resolve.SubmitForm</code></a>:</p>
-<pre><code class="language-python">email_body: str = form.label("Email body", widget=form.Widget.TEXTAREA)
-</code></pre>
-<p>From <a href="/ref/atr/shared/resolve.py:SubmitForm"><code>resolve.SubmitForm</code></a>:</p>
-<pre><code class="language-python">vote_result: Literal["Passed", "Failed"] = form.label("Vote result", widget=form.Widget.RADIO)
-</code></pre>
-<p>From <a href="/ref/atr/shared/vote.py:CastVoteForm"><code>vote.CastVoteForm</code></a>:</p>
-<pre><code class="language-python">decision: Literal["+1", "0", "-1"] = form.label("Your vote", widget=form.Widget.CUSTOM)
-</code></pre>
-<h3 id="using-forms-in-routes">Using forms in routes</h3>
-<p>To use a form in a route, use the <a href="/ref/atr/blueprints/post.py:committer"><code>@post.committer()</code></a> decorator to get the session and auth the user, and the <a href="/ref/atr/blueprints/post.py:form"><code>@post.form()</code></a> decorator to parse and validate input data:</p>
-<pre><code class="language-python">@post.committer("/keys/add")
-@post.form(shared.keys.AddOpenPGPKeyForm)
-async def add(session: web.Committer, add_openpgp_key_form: shared.keys.AddOpenPGPKeyForm) -&gt; web.WerkzeugResponse:
-    """Add a new public signing key to the user's account."""
-    try:
-        key_text = add_openpgp_key_form.public_key
-        selected_committee_names = add_openpgp_key_form.selected_committees
-
-        # Process the validated form data...
-        async with storage.write() as write:
-            # ...
-
-        await quart.flash("OpenPGP key added successfully.", "success")
-    except web.FlashError as e:
-        await quart.flash(str(e), "error")
-    except Exception as e:
-        log.exception("Error adding OpenPGP key:")
-        await quart.flash(f"An unexpected error occurred: {e!s}", "error")
-
-    return await session.redirect(get.keys.keys)
-</code></pre>
-<p>The <a href="/ref/atr/form.py:validate"><code>form.validate</code></a> function should only be called manually when the request comes from JavaScript, as in <a href="/ref/atr/post/preview.py:announce_preview"><code>announce_preview</code></a>. It takes the form class, the form data dictionary, and an optional context dictionary. If validation succeeds, it returns an instance of your form class with validated data. If validation fails, it raises a <code>pydantic.ValidationError</code>.</p>
-<p>The error handling uses <a href="/ref/atr/form.py:flash_error_data"><code>form.flash_error_data</code></a> to prepare error information for display, and <a href="/ref/atr/form.py:flash_error_summary"><code>form.flash_error_summary</code></a> to create a user-friendly summary of all validation errors.</p>
-<h3 id="rendering-forms">Rendering forms</h3>
-<p>The <code>form</code> module provides the <a href="/ref/atr/form.py:render"><code>form.render</code></a> function (or <a href="/ref/atr/form.py:render_block"><code>form.render_block</code></a> for use with <a href="/ref/atr/htm.py:Block"><code>htm.Block</code></a>) that generates Bootstrap-styled HTML. This function creates a two-column layout with labels on the left and inputs on the right:</p>
-<pre><code class="language-python">form.render_block(
-    page,
-    model_cls=shared.keys.AddOpenPGPKeyForm,
-    action=util.as_url(post.keys.add),
-    submit_label="Add OpenPGP key",
-    cancel_url=util.as_url(keys),
-    defaults={
-        "selected_committees": committee_choices,
-    },
-)
-</code></pre>
-<p>The <code>defaults</code> parameter accepts a dictionary to populate initial field values. For checkbox/radio groups and select dropdowns, you can pass a list of <code>(value, label)</code> tuples to dynamically provide choices. The <code>render</code> function returns htpy elements which you can embed in templates or return directly from route handlers.</p>
-<p>Key rendering parameters:</p>
-<ul>
-<li><code>action</code> - form submission URL (defaults to current path)</li>
-<li><code>submit_label</code> - text for the submit button</li>
-<li><code>cancel_url</code> - if provided, adds a cancel link next to submit</li>
-<li><code>defaults</code> - dictionary of initial values or dynamic choices</li>
-<li><code>textarea_rows</code> - number of rows for textarea widgets (default: 12)</li>
-<li><code>wider_widgets</code> - use wider input column (default: False)</li>
-<li><code>border</code> - add borders between fields (default: False)</li>
-</ul>
-<h2 id="programmatic-html">Programmatic HTML</h2>
-<p>Sometimes you need to generate HTML in Python rather than in a template. For this we use <a href="https://htpy.dev/">htpy</a>, which provides a Python API for building HTML elements. You import <code>htpy</code> and then use it like this:</p>
-<pre><code class="language-python">import htpy
-
-element = htpy.div(".container")[
-    htpy.h1["Release Candidate"],
-    htpy.p["This is a release candidate."],
-]
-</code></pre>
-<p>The square brackets syntax is how htpy accepts children. The parentheses syntax is for attributes. If you want a div with an id, you write <code>htpy.div(id="content")</code>. If you want a div with a class, you can use CSS selector syntax like <code>htpy.div(".my-class")</code> or you can use <code>htpy.div(class_="my-class")</code>, remembering to use the underscore in <code>class_</code>.</p>
-<p>You can nest elements arbitrarily, mix strings and elements, and pass lists of elements. Converting an htpy element to a string renders it as HTML. Templates can therefore render htpy elements directly by passing them as variables.</p>
-<p>The htpy library provides type annotations for HTML elements. It does not validate attribute names or values, so you can pass nonsensical attributes without error. We plan to fix this by adding stricter types in our <code>htm</code> wrapper. The main benefit to using <code>htpy</code> (via <code>htm</code>) is having a clean Python API for HTML generation rather than concatenating strings or using templating.</p>
-<h2 id="the-htmblock-class">The htm.Block class</h2>
-<p>The ATR <a href="/ref/atr/htm.py"><code>htm</code></a> module extends htpy with a <a href="/ref/atr/htm.py:Block"><code>Block</code></a> class that makes it easier to build complex HTML structures incrementally. You create a block, append elements to it, and then collect them into a final element. Here is the typical usage pattern:</p>
-<pre><code class="language-python">import atr.htm as htm
-
-div = htm.Block()
-div.h1["Release Information"]
-div.p["The release was created on ", release.created.isoformat(), "."]
-if release.released:
-    div.p["It was published on ", release.released.isoformat(), "."]
-return div.collect()
-</code></pre>
-<p>The block class provides properties for common HTML elements like <code>h1</code>, <code>h2</code>, <code>p</code>, <code>div</code>, <code>ul</code>, and so on. When you access these properties, you get back a <a href="/ref/atr/htm.py:BlockElementCallable"><code>BlockElementCallable</code></a>, which you can call to create an element with attributes or use square brackets to add grandchildren of the block. The element is automatically appended to the block's internal list of children.</p>
-<p>The <code>collect</code> method assembles all of the elements into a single htpy element. If you created the block with an outer element like <code>htm.Block(htpy.div(".container"))</code>, that element wraps all the children. If you created the block with no outer element, <code>collect</code> wraps everything in a div. You can also pass a <code>separator</code> argument to <code>collect</code>, which inserts a text separator between elements.</p>
-<p>The block class is useful when you are building HTML in a loop or when you have conditional elements. Instead of managing a list of elements manually, you can let the block class do it for you: append elements as you go, and at the end call <code>collect</code> to get the final result. This is cleaner than concatenating strings or maintaining lists yourself.</p>
-<p>The block class also adds a <code>data-src</code> attribute to elements, which records which function created the element. If you see an element in the browser inspector with <code>data-src="atr.get.keys:keys"</code>, you know that it came from the <code>keys</code> function in <code>get/keys.py</code>. The source is extracted automatically using <a href="/ref/atr/log.py:caller_name"><code>log.caller_name</code></a>.</p>
-<h2 id="how-a-route-renders-ui">How a route renders UI</h2>
-<p>A typical route that renders UI first authenticates the user, loads data from the database, builds HTML using htpy, and renders it using a template. GET and POST requests are handled by separate routes, with form validation automatically handled by the <a href="/ref/atr/blueprints/post.py:form"><code>@post.form()</code></a> decorator. Here is a simplified example from <a href="/ref/atr/get/keys.py:add"><code>get/keys.py</code></a>:</p>
-<pre><code class="language-python">@get.committer("/keys/add")
-async def add(session: web.Committer) -&gt; str:
-    """Add a new public signing key to the user's account."""
-    async with storage.write() as write:
-        participant_of_committees = await write.participant_of_committees()
-
-    committee_choices = [(c.name, c.display_name or c.name) for c in participant_of_committees]
-
-    page = htm.Block()
-    page.p[htm.a(".atr-back-link", href=util.as_url(keys))["← Back to Manage keys"]]
-    page.div(".my-4")[
-        htm.h1(".mb-4")["Add your OpenPGP key"],
-        htm.p["Add your public key to use for signing release artifacts."],
-    ]
-
-    form.render_block(
-        page,
-        model_cls=shared.keys.AddOpenPGPKeyForm,
-        action=util.as_url(post.keys.add),
-        submit_label="Add OpenPGP key",
-        cancel_url=util.as_url(keys),
-        defaults={
-            "selected_committees": committee_choices,
-        },
-    )
-    ...
-    return await template.blank(
-        "Add your OpenPGP key",
-        content=page.collect(),
-        description="Add your public signing key to your ATR account.",
-    )
-</code></pre>
-<p>The route is decorated with <a href="/ref/atr/blueprints/get.py:committer"><code>@get.committer()</code></a>, which handles authentication and provides a <code>session</code> object that is an instance of <a href="/ref/atr/web.py:Committer"><code>web.Committer</code></a> with a range of useful properties and methods.</p>
-<p>The function builds the UI using an <a href="/ref/atr/htm.py:Block"><code>htm.Block</code></a> object, which provides a convenient API for incrementally building HTML. The form is rendered directly into the block using <a href="/ref/atr/form.py:render_block"><code>form.render_block()</code></a>, which generates all the necessary HTML with Bootstrap styling.</p>
-<p>Finally, the route returns the rendered HTML using <a href="/ref/atr/template.py:blank"><code>template.blank()</code></a>, which renders a minimal template with just a title and content area.</p>
-<p>Form submission is handled by a separate POST route:</p>
-<pre><code class="language-python">@post.committer("/keys/add")
-@post.form(shared.keys.AddOpenPGPKeyForm)
-async def add(session: web.Committer, add_openpgp_key_form: shared.keys.AddOpenPGPKeyForm) -&gt; web.WerkzeugResponse:
-    """Add a new public signing key to the user's account."""
-    try:
-        key_text = add_openpgp_key_form.public_key
-        selected_committee_names = add_openpgp_key_form.selected_committees
-
-        # Process the validated form data...
-
-        await quart.flash("OpenPGP key added successfully.", "success")
-    except web.FlashError as e:
-        await quart.flash(str(e), "error")
-
-    return await session.redirect(get.keys.keys)
-</code></pre>
-<p>The <a href="/ref/atr/blueprints/post.py:form"><code>@post.form()</code></a> decorator handles form validation automatically. If validation fails, it flashes error messages and redirects back to the GET route. If validation succeeds, the validated form instance is injected into the route handler as a parameter.</p>
-<p>Bootstrap CSS classes are applied automatically by the form rendering functions. The functions use classes like <code>form-control</code>, <code>form-select</code>, <code>btn-primary</code>, <code>is-invalid</code>, and <code>invalid-feedback</code>. We currently use Bootstrap 5. If you generate HTML manually with htpy, you can apply Bootstrap classes yourself by using the CSS selector syntax like <code>htpy.div(".container")</code> or the class attribute like <code>htpy.div(class_="c [...]
diff --git a/atr/get/docs.py b/atr/get/docs.py
index 40e6047..b700433 100644
--- a/atr/get/docs.py
+++ b/atr/get/docs.py
@@ -59,7 +59,7 @@ async def page(session: web.Committer | None, page: str) -> str:
 
 
 async def _serve_docs_page(page: str) -> str:
-    docs_dir = pathlib.Path(config.get().PROJECT_ROOT) / "atr" / "docs"
+    docs_dir = pathlib.Path(config.get().PROJECT_ROOT) / "docs"
 
     if not page.endswith(".html"):
         page = f"{page}.html"


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org