From 4cf6179e6e2c5e6120f0e9a80bd0e4948e4e424b Mon Sep 17 00:00:00 2001 From: njzjz-bot Date: Tue, 21 Jul 2026 14:11:51 +0800 Subject: [PATCH 1/4] docs: parallelize Read the Docs HTML build Override the Read the Docs HTML command to use two Sphinx workers while preserving the existing builder, language, doctree, and output settings. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh --- .readthedocs.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 4b829fc279..7f0340233b 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -8,6 +8,11 @@ build: - pip install uv post_install: - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv pip install -r doc/requirements.txt + build: + html: + # Limit Sphinx to two workers so generated API pages can be processed + # concurrently without multiplying backend import memory excessively. + - python -m sphinx -T -j 2 -b html -d doc/_build/doctrees -D language=en doc $READTHEDOCS_OUTPUT/html apt_packages: - inkscape sphinx: From ba8f9c64cbc01ece45423c830bb394538686e7d9 Mon Sep 17 00:00:00 2001 From: njzjz-bot Date: Sat, 25 Jul 2026 09:56:36 +0800 Subject: [PATCH 2/4] fix(docs): bound Read the Docs Sphinx build Run the custom Sphinx command from the documentation directory so the source checkout does not shadow the installed package. Add a 45-minute timeout with a forced-kill grace period to turn stalled parallel builds into explicit failures. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh --- .readthedocs.yml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 7f0340233b..403d8aeae4 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -10,9 +10,19 @@ build: - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv pip install -r doc/requirements.txt build: html: + # Custom build jobs start at the repository root, unlike Read the + # Docs-generated Sphinx command, which starts in the documentation + # directory. Preserve that working directory so the checkout does not + # shadow the installed package and hide its generated ``deepmd.lib``. + # Bound the command so a wedged extension or worker is terminated and + # reported as a failed build instead of occupying a builder forever. # Limit Sphinx to two workers so generated API pages can be processed # concurrently without multiplying backend import memory excessively. - - python -m sphinx -T -j 2 -b html -d doc/_build/doctrees -D language=en doc $READTHEDOCS_OUTPUT/html + - >- + cd doc && + timeout --signal=TERM --kill-after=30s 45m + python -m sphinx -T -j 2 -b html -d _build/doctrees + -D language=en . $READTHEDOCS_OUTPUT/html apt_packages: - inkscape sphinx: From eed8f9cfcbb80bf98c0b819ae28a257e48419be8 Mon Sep 17 00:00:00 2001 From: njzjz-bot Date: Mon, 27 Jul 2026 19:33:45 +0800 Subject: [PATCH 3/4] docs: implement merge_domaindata for the dargs domain dargs.sphinx.DargsDomain advertises parallel_read_safe but does not implement merge_domaindata, so Sphinx refuses to combine the per-worker inventories and -j aborts the build. The domain's only state is a flat targetid -> (docname, objtype) map, so merging is a dict update restricted to the documents the worker read. Verified on a minimal two-page project using dargs directives: -j 2 fails with the same NotImplementedError without the shim and succeeds with it. --- doc/conf.py | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 216b4d5c73..d07e6ba5f4 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -237,13 +237,24 @@ # deeper than that are left unnumbered. Only the listed pages are affected. from typing import ( TYPE_CHECKING, + Any, ) +from dargs.sphinx import ( + DargsDomain, +) from docutils import ( nodes, ) +from sphinx.domains import ( + Domain, +) if TYPE_CHECKING: + from collections.abc import ( + Iterable, + ) + from sphinx.application import ( Sphinx, ) @@ -276,6 +287,26 @@ def _cap_cli_secnumbers(app: Sphinx, doctree: nodes.document, docname: str) -> N break +def _merge_dargs_domaindata( + self: Domain, docnames: Iterable[str], otherdata: dict[str, Any] +) -> None: + """Merge ``dargs`` argument entries collected by a parallel read worker. + + ``dargs.sphinx.DargsDomain`` advertises ``parallel_read_safe`` but does not + implement ``merge_domaindata``, so Sphinx refuses to combine the per-worker + inventories and ``-j`` aborts the build. The domain's only state is a flat + ``targetid -> (docname, objtype)`` map, so merging is a plain dict update + restricted to the documents this worker actually read. + """ + docnames = set(docnames) + arguments = self.data["arguments"] + for targetid, entry in otherdata["arguments"].items(): + if entry[0] in docnames: + arguments[targetid] = entry + + def setup(app: Sphinx) -> dict[str, bool]: + if DargsDomain.merge_domaindata is Domain.merge_domaindata: + DargsDomain.merge_domaindata = _merge_dargs_domaindata app.connect("doctree-resolved", _cap_cli_secnumbers) return {"parallel_read_safe": True, "parallel_write_safe": True} From c43224bd7196e3c5638c76a57df49b78328980e0 Mon Sep 17 00:00:00 2001 From: njzjz-bot Date: Tue, 11 Aug 2026 02:35:35 +0800 Subject: [PATCH 4/4] docs: fit RTD timeout within build limit Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 403d8aeae4..5776806dbd 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -20,7 +20,7 @@ build: # concurrently without multiplying backend import memory excessively. - >- cd doc && - timeout --signal=TERM --kill-after=30s 45m + timeout --signal=TERM --kill-after=30s 30m python -m sphinx -T -j 2 -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html apt_packages: