Changeset View
Changeset View
Standalone View
Standalone View
swh/docs/sphinx/conf.py
#!/usr/bin/env python3 | #!/usr/bin/env python3 | ||||
# -*- coding: utf-8 -*- | # -*- coding: utf-8 -*- | ||||
# | # | ||||
import logging | |||||
import os | import os | ||||
from typing import Dict | from typing import Dict | ||||
from sphinx.ext import autodoc | from sphinx.ext import autodoc | ||||
from swh.docs.django_settings import force_django_settings | from swh.docs.django_settings import force_django_settings | ||||
# General information about the project. | # General information about the project. | ||||
▲ Show 20 Lines • Show All 148 Lines • ▼ Show 20 Lines | |||||
_swh_web_base_url = "https://archive.softwareheritage.org" | _swh_web_base_url = "https://archive.softwareheritage.org" | ||||
# for the extlinks extension, sub-projects should fill that dict | # for the extlinks extension, sub-projects should fill that dict | ||||
extlinks: Dict = { | extlinks: Dict = { | ||||
"swh_web": (f"{_swh_web_base_url}/%s", None), | "swh_web": (f"{_swh_web_base_url}/%s", None), | ||||
"swh_web_api": (f"{_swh_web_base_url}/api/1/%s", None), | "swh_web_api": (f"{_swh_web_base_url}/api/1/%s", None), | ||||
"swh_web_browse": (f"{_swh_web_base_url}/browse/%s", None), | "swh_web_browse": (f"{_swh_web_base_url}/browse/%s", None), | ||||
} | } | ||||
vlorentz: Please add a docstring/commentto explain when it is set.
And explain it in `swh-docs/README. | |||||
# SWH_PACKAGE_DOC_TOX_BUILD environment variable is set in a tox | |||||
# environment named sphinx for each swh package (defined in tox.ini file) | |||||
vlorentzUnsubmitted Not Done Inline Actionsexcept the swh-docs package itself vlorentz: 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: | |||||
rst_prolog = ".. include:: /../.tox/sphinx/src/swh-docs/docs/swh_substitutions" | |||||
suppress_warnings = ["ref.ref"] | |||||
html_favicon = "" | |||||
html_logo = "" | |||||
class SimpleDocumenter(autodoc.FunctionDocumenter): | class SimpleDocumenter(autodoc.FunctionDocumenter): | ||||
""" | """ | ||||
Custom autodoc directive to inline the docstring of a function | Custom autodoc directive to inline the docstring of a function | ||||
in a document without the signature header and with no indentation. | in a document without the signature header and with no indentation. | ||||
Example of use:: | Example of use:: | ||||
Show All 34 Lines | def set_django_settings(app, env, docname): | ||||
} | } | ||||
for package, settings in package_settings.items(): | for package, settings in package_settings.items(): | ||||
if any( | if any( | ||||
[pattern in docname for pattern in (f"swh.{package}", f"swh-{package}")] | [pattern in docname for pattern in (f"swh.{package}", f"swh-{package}")] | ||||
): | ): | ||||
force_django_settings(settings) | 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): | def setup(app): | ||||
# env-purge-doc event is fired before source-read | # env-purge-doc event is fired before source-read | ||||
app.connect("env-purge-doc", set_django_settings) | app.connect("env-purge-doc", set_django_settings) | ||||
# add autosimple directive (used in swh-web) | # add autosimple directive (used in swh-web) | ||||
app.add_autodocumenter(SimpleDocumenter) | app.add_autodocumenter(SimpleDocumenter) | ||||
# set an environment variable indicating we are currently building | # set an environment variable indicating we are currently building | ||||
# the documentation | # the documentation | ||||
os.environ["SWH_DOC_BUILD"] = "1" | os.environ["SWH_DOC_BUILD"] = "1" | ||||
# register routingtable label for sphinxcontrib-httpdomain <= 1.7.0 | # register routingtable label for sphinxcontrib-httpdomain <= 1.7.0 | ||||
from distutils.version import StrictVersion # noqa | from distutils.version import StrictVersion # noqa | ||||
import pkg_resources # noqa | import pkg_resources # noqa | ||||
httpdomain = pkg_resources.get_distribution("sphinxcontrib-httpdomain") | httpdomain = pkg_resources.get_distribution("sphinxcontrib-httpdomain") | ||||
if StrictVersion(httpdomain.version) <= StrictVersion("1.7.0"): | if StrictVersion(httpdomain.version) <= StrictVersion("1.7.0"): | ||||
app.connect("doctree-read", register_routingtable_as_label) | 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") | |||||
Not Done Inline Actionsshouldn't this be turned off when building swh-web's doc? (not a big deal if it isn't) vlorentz: shouldn't this be turned off when building swh-web's doc? (not a big deal if it isn't) | |||||
logger = logging.getLogger("sphinx") | |||||
# insert a custom filter in the warning log handler of sphinx | |||||
logger.handlers[1].filters.insert(0, HttpDomainWarningFilter()) |
Please add a docstring/commentto explain when it is set.
And explain it in swh-docs/README.md too