From 6f8dd5d3f24314626d2c709bce07f08a446ce8bc Mon Sep 17 00:00:00 2001
From: Antoine Lambert <antoine.lambert@inria.fr>
Date: Mon, 26 Apr 2021 16:35:27 +0200
Subject: [PATCH] tox: Add sphinx environments to check sane doc build

Enable to check package documentation can be built without producing
sphinx warnings.

The sphinx environment is designed to be used in continuous integration
in order to prevent breaking documentation build when committing changes.

The sphinx-dev environment is designed to be used inside a full swh
development environment.

Related to T3258
---
 tox.ini | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/tox.ini b/tox.ini
index 75fc54f..66e29ea 100644
--- a/tox.ini
+++ b/tox.ini
@@ -37,3 +37,41 @@ deps =
   mypy
 commands =
   mypy swh
+
+# build documentation outside swh-environment using the current
+# git HEAD of swh-docs, is executed on CI for each diff to prevent
+# breaking doc build
+[testenv:sphinx]
+whitelist_externals = make
+usedevelop = true
+extras =
+  testing
+deps =
+  # fetch and install swh-docs in develop mode
+  -e git+https://forge.softwareheritage.org/source/swh-docs#egg=swh.docs
+
+setenv =
+  SWH_PACKAGE_DOC_TOX_BUILD = 1
+  # turn warnings into errors
+  SPHINXOPTS = -W
+commands =
+  make -I ../.tox/sphinx/src/swh-docs/swh/ -C docs
+
+
+# build documentation only inside swh-environment using local state
+# of swh-docs package
+[testenv:sphinx-dev]
+whitelist_externals = make
+usedevelop = true
+extras =
+  testing
+deps =
+  # install swh-docs in develop mode
+  -e ../swh-docs
+
+setenv =
+  SWH_PACKAGE_DOC_TOX_BUILD = 1
+  # turn warnings into errors
+  SPHINXOPTS = -W
+commands =
+  make -I ../.tox/sphinx-dev/src/swh-docs/swh/ -C docs