diff --git a/swh/docs/sphinx/conf.py b/swh/docs/sphinx/conf.py
--- a/swh/docs/sphinx/conf.py
+++ b/swh/docs/sphinx/conf.py
@@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 #
 
+import logging
 import os
 from typing import Dict
 
@@ -167,6 +168,17 @@
     "swh_web_browse": (f"{_swh_web_base_url}/browse/%s", None),
 }
 
+swh_package_doc_tox_build = os.environ.get("SWH_PACKAGE_DOC_TOX_BUILD", False)
+
+# override some configuration when building a swh package
+# documentation with tox to remove warnings and suppress
+# those related to unresolved references
+if swh_package_doc_tox_build:
+    rst_prolog = ".. include:: /../.tox/sphinx/src/swh-docs/docs/swh_substitutions"
+    suppress_warnings = ["ref.ref"]
+    html_favicon = ""
+    html_logo = ""
+
 
 class SimpleDocumenter(autodoc.FunctionDocumenter):
     """
@@ -217,6 +229,18 @@
             force_django_settings(settings)
 
 
+# when building local package documentation with tox, insert glossary
+# content at the end of the index file in order to resolve references
+# to the terms it contains
+def add_glossary_to_index(app, docname, source):
+    if docname == "index":
+        glossary_path = os.path.join(
+            os.path.dirname(__file__), "../../../docs/glossary.rst"
+        )
+        with open(glossary_path, "r") as glossary:
+            source[0] += "\n" + glossary.read()
+
+
 def setup(app):
     # env-purge-doc event is fired before source-read
     app.connect("env-purge-doc", set_django_settings)
@@ -234,3 +258,17 @@
     httpdomain = pkg_resources.get_distribution("sphinxcontrib-httpdomain")
     if StrictVersion(httpdomain.version) <= StrictVersion("1.7.0"):
         app.connect("doctree-read", register_routingtable_as_label)
+
+    if swh_package_doc_tox_build:
+        # ensure glossary will be available in package doc scope
+        app.connect("source-read", add_glossary_to_index)
+
+        # filter out httpdomain unresolved reference warnings
+        # to not consider them as errors when using -W option of sphinx-build
+        class HttpDomainWarningFilter(logging.Filter):
+            def filter(self, record: logging.LogRecord) -> bool:
+                return not record.msg.startswith("Cannot resolve reference to")
+
+        logger = logging.getLogger("sphinx")
+        # insert a custom filter in the warning log handler of sphinx
+        logger.handlers[1].filters.insert(0, HttpDomainWarningFilter())