diff --git a/tox.ini b/tox.ini
--- a/tox.ini
+++ b/tox.ini
@@ -49,3 +49,29 @@
   mypy
 commands =
   mypy swh
+
+[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.git#egg=swh.docs
+  # swh-docs import django settings for deposit and web in its conf.py
+  swh.deposit
+  swh.web
+
+setenv =
+  # fix rst prolog include
+  SPHINXOPTS1 = -D rst_prolog=".. include:: /../.tox/sphinx/src/swh-docs/docs/swh_substitutions"
+  # suppress warnings related to refs in other swh packages and missing images
+  SPHINXOPTS2 = -D suppress_warnings=ref.term,ref.ref -D html_favicon= -D html_logo=
+  # turn warnings into errors
+  SPHINXOPTS = -W {env:SPHINXOPTS1} {env:SPHINXOPTS2}
+commands =
+  make -I ../.tox/sphinx/src/swh-docs/swh/ -C docs