diff --git a/docs/Makefile b/docs/Makefile
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,3 +1,15 @@
 include ../../swh-docs/Makefile.sphinx
 
 APIDOC_EXCLUDES += ../swh/*/settings/*
+
+sphinx/html: images
+sphinx/clean: clean-images
+
+images:
+	make -C images/
+clean-images:
+	make -C images/ clean
+
+clean: clean-images
+
+.PHONY: images clean-images
diff --git a/tox.ini b/tox.ini
--- a/tox.ini
+++ b/tox.ini
@@ -41,3 +41,41 @@
   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
\ No newline at end of file