Refactor the documentation build process (#311)

* Refactor the documentation build process Significant improvements: * Allow easy isolated local builds via a dedicated Tox environment * Configure Sphinx to use consistent packages and theme across local, CI, and ReadTheDocs builds; local builds now look the same as the published RTD pages * Explicitly add a ReadTheDocs configuration as code, per their documented best practices * Remove lots of dead code and simplify the Sphinx configuration file * Build docs in a dedicated CI step and enable stricter warning checking * Fix docutils related build error. * Relax Sphinx version. * Invalidate RTD build cache. * No need to combine coverage reporting I think. * Add combining again. Co-authored-by: Jannis Leidel <jannis@leidel.info>
jazzband · Nov 8, 2021 · 93e628e · 93e628e
1 parent 7ff2985
commit 93e628e
Show file tree

Hide file tree

Showing 12 changed files with 64 additions and 684 deletions.
diff --git a/.gitignore b/.gitignore
@@ -9,5 +9,4 @@ build/
 htmlcov/
 *.pyc
 dist/
-tests/docs/_build/
 .eggs/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,16 @@
+---
+version: 2
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+sphinx:
+  configuration: docs/conf.py
+formats:
+  - epub
+  - pdf
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,4 +1,5 @@
 include .pre-commit-config.yaml
+include .readthedocs.yaml
 include AUTHORS
 include CODE_OF_CONDUCT.md
 include CONTRIBUTING.md

diff --git a/docs/Makefile b/docs/Makefile
-Original file line number
+Diff line change
@@ Expand Up / @@ -9,5 +9,4 @@ build/ @@
     htmlcov/
     *.pyc
     dist/
-    tests/docs/_build/
     .eggs/