From 31a4a5ee8c739d0163d87bcf965a1bb700b192d9 Mon Sep 17 00:00:00 2001 From: Emma Anholt Date: Wed, 5 Nov 2025 09:10:59 -0800 Subject: [PATCH] docs: Give more reproducible instructions for how to build the docs. I routinely don't update the docs because the build (hawkmoth in particular) is a pain. The prior instructions almost worked, except that on Debian you need to use a venv (which is a good idea to do for py3-clang as well for reproducibility, anyway), and the versions that were listed didn't actually run any more due to a revoked dependency. Part-of: --- docs/submittingpatches.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/submittingpatches.rst b/docs/submittingpatches.rst index 5519442fc57..19fb7b06dac 100644 --- a/docs/submittingpatches.rst +++ b/docs/submittingpatches.rst @@ -497,11 +497,12 @@ Our documentation is written as `reStructuredText`_ files in the .. code-block:: sh # Install dependencies (adapt for your distribution) - apk add coreutils graphviz py3-clang clang-dev musl-dev linux-headers - pip3 install sphinx===5.1.1 mako===1.2.3 hawkmoth===0.16.0 + apk add coreutils graphviz clang-dev musl-dev linux-headers + python3 -m venv docs-build + ./docs-build/bin/pip3 install sphinx===8.2.3 mako===1.2.3 hawkmoth===0.19.0 clang===$(llvm-config --version) - # Build docs - sphinx-build -W -b html docs docs-html/ + # Build docs (on Debian, set LD_LIBRARY_PATH to /usr/lib/llvm-VERSION/lib so it can find libclang.so) + ./docs-build/bin/sphinx-build -W -b html docs docs-html/ The preferred language of the documentation is US English. This doesn't mean that everyone is expected to pay close attention to