MAINT: write sphinx-build flags full

ComPWA · Sep 11, 2024 · a5a6b95 · a5a6b95
1 parent f5b129f
commit a5a6b95
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 27 deletions.
diff --git a/pyproject.toml b/pyproject.toml
@@ -241,34 +241,34 @@ pytest tests/unit \
 [tool.pixi.feature.dev.tasks.doc]
 cmd = """
 sphinx-build \
+    --builder html \
     --keep-going \
-    -TW \
-    -b html \
+    --show-traceback --fail-on-warning \
     docs/ docs/_build/html
 """
 env = {FORCE_COLOR = "yes"}
 
 [tool.pixi.feature.dev.tasks.doclive]
 cmd = """
 sphinx-autobuild \
+    --builder html \
     --open-browser \
-    --re-ignore '.*/.ipynb_checkpoints/.*' \
     --re-ignore '.*/__pycache__/.*' \
+    --re-ignore '.*/.ipynb_checkpoints/.*' \
     --re-ignore '.*\\.tmp' \
+    --re-ignore 'docs/_build/.*' \
+    --re-ignore 'docs/_images/.*' \
+    --re-ignore 'docs/_static/logo\\..*' \
     --re-ignore 'docs/.*\\.csv' \
     --re-ignore 'docs/.*\\.gv' \
     --re-ignore 'docs/.*\\.inv' \
     --re-ignore 'docs/.*\\.json' \
     --re-ignore 'docs/.*\\.pickle' \
     --re-ignore 'docs/.*\\.yaml' \
     --re-ignore 'docs/.*\\.yml' \
-    --re-ignore 'docs/_build/.*' \
-    --re-ignore 'docs/_images/.*' \
-    --re-ignore 'docs/_static/logo\\..*' \
     --re-ignore 'docs/api/.*' \
     --watch docs \
     --watch src \
-    -b html \
     docs/ docs/_build/html
 """
 env = {FORCE_COLOR = "yes"}
@@ -288,8 +288,8 @@ env = {EXECUTE_NB = "yes", FORCE_COLOR = "yes", PYTHONHASHSEED = "0"}
 [tool.pixi.feature.dev.tasks.linkcheck]
 cmd = """
 sphinx-build \
-    -T \
-    -b linkcheck \
+    --builder linkcheck \
+    --show-traceback \
     docs/ docs/_build/linkcheck
 """
 env = {FORCE_COLOR = "yes"}

diff --git a/tox.ini b/tox.ini
@@ -32,9 +32,10 @@ allowlist_externals =
   sphinx-build
 commands =
   sphinx-build \
+    --builder html \
+    --fail-on-warning \
     --keep-going \
-    -TW \
-    -b html \
+    --show-traceback \
     docs/ docs/_build/html
 description =
   Build documentation and API through Sphinx
@@ -47,24 +48,24 @@ allowlist_externals =
   sphinx-autobuild
 commands =
   sphinx-autobuild \
+    --builder html \
     --open-browser \
-    --re-ignore .*/.ipynb_checkpoints/.* \
     --re-ignore .*/__pycache__/.* \
+    --re-ignore .*/.ipynb_checkpoints/.* \
     --re-ignore .*\.tmp \
+    --re-ignore docs/_build/.* \
+    --re-ignore docs/_images/.* \
+    --re-ignore docs/_static/logo\..* \
     --re-ignore docs/.*\.csv \
     --re-ignore docs/.*\.gv \
     --re-ignore docs/.*\.inv \
     --re-ignore docs/.*\.json \
     --re-ignore docs/.*\.pickle \
     --re-ignore docs/.*\.yaml \
     --re-ignore docs/.*\.yml \
-    --re-ignore docs/_build/.* \
-    --re-ignore docs/_images/.* \
-    --re-ignore docs/_static/logo\..* \
     --re-ignore docs/api/.* \
     --watch docs \
     --watch src \
-    -b html \
     docs/ docs/_build/html
 description =
   Set up a server to directly preview changes to the HTML pages
@@ -77,9 +78,9 @@ allowlist_externals =
   sphinx-build
 commands =
   sphinx-build \
+    --builder html \
     --keep-going \
-    -TW \
-    -b html \
+    --show-traceback --fail-on-warning \
     docs/ docs/_build/html
 description =
   Build documentation through Sphinx WITH output of Jupyter notebooks
@@ -94,24 +95,24 @@ allowlist_externals =
   sphinx-autobuild
 commands =
   sphinx-autobuild \
+    --builder html \
     --open-browser \
-    --re-ignore .*/.ipynb_checkpoints/.* \
     --re-ignore .*/__pycache__/.* \
+    --re-ignore .*/.ipynb_checkpoints/.* \
     --re-ignore .*\.tmp \
+    --re-ignore docs/_build/.* \
+    --re-ignore docs/_images/.* \
+    --re-ignore docs/_static/logo\..* \
     --re-ignore docs/.*\.csv \
     --re-ignore docs/.*\.gv \
     --re-ignore docs/.*\.inv \
     --re-ignore docs/.*\.json \
     --re-ignore docs/.*\.pickle \
     --re-ignore docs/.*\.yaml \
     --re-ignore docs/.*\.yml \
-    --re-ignore docs/_build/.* \
-    --re-ignore docs/_images/.* \
-    --re-ignore docs/_static/logo\..* \
     --re-ignore docs/api/.* \
     --watch docs \
     --watch src \
-    -b html \
     docs/ docs/_build/html
 description =
   Set up a server to directly preview changes to the HTML pages
@@ -126,9 +127,9 @@ allowlist_externals =
   sphinx-build
 commands =
   sphinx-build \
+    --builder html \
+    --fail-on-warning \
     --keep-going \
-    -b html \
-    -nW \
     docs/ docs/_build/html
 description =
   Execute ALL Jupyter notebooks and build documentation with Sphinx
@@ -152,8 +153,8 @@ allowlist_externals =
   sphinx-build
 commands =
   sphinx-build \
-    -T \
-    -b linkcheck \
+    --builder linkcheck \
+    --show-traceback \
     docs/ docs/_build/linkcheck
 description =
   Check external links in the documentation (requires internet connection)