diff --git a/tox.ini b/tox.ini
index 5d7ab80..6b2c32a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,51 +1,97 @@
 [tox]
 envlist=black,flake8,mypy,py3-{core,db,server}
 
 [testenv]
 passenv = PYTHONASYNCIODEBUG
 extras =
   testing-core
   core: logging
   db: db, testing-db
   server: http
 deps =
   cover: pytest-cov
 commands =
   pytest --doctest-modules \
   slow: --hypothesis-profile=slow \
   cover: --cov={envsitepackagesdir}/swh/core --cov-branch \
   core: {envsitepackagesdir}/swh/core/tests \
   db: {envsitepackagesdir}/swh/core/db/tests \
   server: {envsitepackagesdir}/swh/core/api/tests \
     {posargs}
 
 [testenv:py3]
 skip_install = true
 deps = tox
 commands = tox -e py3-core-db-server-slow-cover -- {posargs}
 
 [testenv:black]
 skip_install = true
 deps =
   black==19.10b0
 commands =
   {envpython} -m black --check swh
 
 [testenv:flake8]
 skip_install = true
 deps =
   flake8
 commands =
   {envpython} -m flake8
 
 [testenv:mypy]
 extras =
   testing-core
   logging
   db
   testing-db
   http
 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-core
+  logging
+  db
+  testing-db
+  http
+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-core
+  logging
+  db
+  testing-db
+  http
+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