♲🎨 Evolve docs building tox env

1 files changed, 14 insertions, 1 deletions

diff --git a/tox.ini b/tox.ini
index 59f7ce55..44ca83b8 100644
--- a/tox.ini
+++ b/tox.ini
@@ -57,9 +57,22 @@ commands =
     python -m setup check --metadata --restructuredtext --strict --verbose
 
 [testenv:build-docs]
+basepython = python3
 extras =
     docs
     testing
 changedir = docs
+# FIXME: Add -W option below once this issue is addressed:
+# https://github.com/jaraco/rst.linker/issues/7
+# And once all other warnings are gone.
 commands =
-    python -m sphinx . {toxinidir}/build/html
+    python -m sphinx \
+      -a -n -j auto \
+      -b html --color \
+      -d "{toxinidir}/build/html_docs_doctree" \
+      . "{toxinidir}/build/html"
+
+    # Print out the output docs dir and a way to serve html:
+    python -c \
+    'import pathlib; '\
+    'docs_dir = pathlib.Path(r"{toxinidir}") / "build" / "html"; index_file = docs_dir / "index.html"; print(f"\nDocumentation available under `file://\{index_file\}`\n\nTo serve docs, use `python3 -m http.server --directory \{docs_dir\} 0`\n")'