Page MenuHomeSoftware Heritage
Files F7066586

D5571.id19967.diff
No OneTemporary
Actions

D5571.id19967.diff
View Options

diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -97,6 +97,23 @@
The publication of the documentation is now managed by the [CI][7].
+Building standalone package documentation
+-----------------------------------------
+
+Each documentation local to a swh package can also be built with [tox][6].
+
+For instance to build the standalone documentation of ``swh-web``, proceed as
+follows:
+
+ $ cd swh-environment/swh-web
+ $ tox -e sphinx-dev
+
+Sphinx warnings related to unresolved references located in other swh packages are suppressed because expected.
+
+Please also note that Sphinx warnings are turned into errors in that case.
+
+The HTML documentation is now available starting from `docs/_build/html/index.html`.
+
[1]: http://www.sphinx-doc.org/
[2]: https://forge.softwareheritage.org/source/swh-environment/
@@ -104,4 +121,4 @@
[4]: http://plantuml.com
[5]: https://inkscape.org/
[6]: https://tox.readthedocs.io/
-[7]: https://github.com/jd/pifpaf
+[7]: https://jenkins.softwareheritage.org/job/DDOC/
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,22 @@
"swh_web_browse": (f"{_swh_web_base_url}/browse/%s", None),
}
+# SWH_PACKAGE_DOC_TOX_BUILD environment variable is set in a tox environment
+# named sphinx for each swh package (except the swh-docs package itself).
+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:
+ swh_substitutions = os.path.join(
+ os.path.dirname(__file__), "../../../docs/swh_substitutions"
+ )
+ rst_prolog = f".. include:: /{swh_substitutions}"
+ suppress_warnings = ["ref.ref"]
+ html_favicon = ""
+ html_logo = ""
+
class SimpleDocumenter(autodoc.FunctionDocumenter):
"""
@@ -217,6 +234,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 +263,20 @@
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)
+
+ # suppress httpdomain warnings in non web packages
+ if "swh-web" not in app.srcdir:
+
+ # 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())

File Metadata

Mime Type
text/plain
Expires
Nov 5 2024, 3:29 PM (11 w, 14 h ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3229438

Event Timeline

About · Developer information · Legal