Differential D5571 Diff 19938 swh/docs/sphinx/conf.py

Changeset 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),
}		}

		vlorentzUnsubmitted Not Done Inline Actions Please add a docstring/commentto explain when it is set. And explain it in `swh-docs/README.md` too 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
		vlorentzUnsubmitted Not Done Inline Actions except the `swh-docs` package itself vlorentz: except the `swh-docs` package itself
		# environment named sphinx for each swh package (defined in tox.ini file)
		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")
		vlorentzUnsubmitted Not Done Inline Actions shouldn'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())