diff --git a/docs/README.rst b/docs/README.rst
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -1,5 +1,3 @@
-.. _swh-py-template:
-
 Software Heritage - Python module template
 ==========================================
 
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,3 +1,5 @@
+.. _swh-py-template:
+
 .. include:: README.rst
 
 .. toctree::
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -36,11 +36,11 @@
     return requirements
 
 
-# Edit this part to match your module.
+# Edit this part to match your module, replace foo by its name
 # Full sample:
 #   https://forge.softwareheritage.org/diffusion/DCORE/browse/master/setup.py
 setup(
-    name="swh.<module-name>",  # example: swh.loader.pypi
+    name="swh.foo",  # example: swh.loader.pypi
     description="Software Heritage <Module's intent>",
     long_description=long_description,
     long_description_content_type="text/x-rst",
@@ -57,7 +57,7 @@
     include_package_data=True,
     entry_points="""
         [swh.cli.subcommands]
-        <cli-name>=swh.<module>.cli
+        foo=swh.foo.cli
     """,
     classifiers=[
         "Programming Language :: Python :: 3",
diff --git a/tox.ini b/tox.ini
--- a/tox.ini
+++ b/tox.ini
@@ -33,3 +33,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