Changeset View
Changeset View
Standalone View
Standalone View
swh/docs/sphinx/conf.py
| Show First 20 Lines • Show All 218 Lines • ▼ Show 20 Lines | class SimpleDocumenter(autodoc.FunctionDocumenter): | ||||
| # do not indent the content | # do not indent the content | ||||
| content_indent = "" | content_indent = "" | ||||
| # do not add a header to the docstring | # do not add a header to the docstring | ||||
| def add_directive_header(self, sig): | def add_directive_header(self, sig): | ||||
| pass | pass | ||||
| # XXX Kill this ASA this PR is accepted and released | |||||
| # https://github.com/sphinx-contrib/httpdomain/pull/19 | |||||
| def register_routingtable_as_label(app, document): | |||||
| from sphinx.locale import _ # noqa | |||||
| labels = app.env.domaindata["std"]["labels"] | |||||
| labels["routingtable"] = "http-routingtable", "", _("HTTP Routing Table") | |||||
| anonlabels = app.env.domaindata["std"]["anonlabels"] | |||||
| anonlabels["routingtable"] = "http-routingtable", "" | |||||
| # sphinx event handler to set adequate django settings prior reading | # sphinx event handler to set adequate django settings prior reading | ||||
| # apidoc generated rst files when building doc to avoid autodoc errors | # apidoc generated rst files when building doc to avoid autodoc errors | ||||
| def set_django_settings(app, env, docname): | def set_django_settings(app, env, docname): | ||||
| if any([pattern in app.srcdir for pattern in ("swh-web-client", "DWCLI")]): | if any([pattern in app.srcdir for pattern in ("swh-web-client", "DWCLI")]): | ||||
| # swh-web-client is detected as swh-web by the code below but | # swh-web-client is detected as swh-web by the code below but | ||||
| # django is not installed when building standalone swh-web-client doc | # django is not installed when building standalone swh-web-client doc | ||||
| return | return | ||||
| package_settings = { | package_settings = { | ||||
| Show All 24 Lines | 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 | |||||
| from distutils.version import StrictVersion # noqa | |||||
| import pkg_resources # noqa | |||||
| httpdomain = pkg_resources.get_distribution("sphinxcontrib-httpdomain") | |||||
| if StrictVersion(httpdomain.version) <= StrictVersion("1.7.0"): | |||||
| app.connect("doctree-read", register_routingtable_as_label) | |||||
| logger = logging.getLogger("sphinx") | logger = logging.getLogger("sphinx") | ||||
| # filter out non critical warnings appeared with sphinx 4.1 release | |||||
| # TODO: remove that hack when that pull request gets merged | |||||
| # https://github.com/sphinx-contrib/httpdomain/pull/51 | |||||
| class HttpDomainRoleWarningFilter(logging.Filter): | |||||
| def filter(self, record: logging.LogRecord) -> bool: | |||||
| return not ( | |||||
| record.args | |||||
| and type(record.args) == tuple # to keep mypy happy | |||||
| and record.args[0] == "http" | |||||
| and record.msg.endswith("but that role is not in the domain.") | |||||
| ) | |||||
| # insert a custom filter in the warning log handler of sphinx | |||||
| logger.handlers[1].filters.insert(0, HttpDomainRoleWarningFilter()) | |||||
| if swh_package_doc_tox_build: | if swh_package_doc_tox_build: | ||||
| # ensure glossary will be available in package doc scope | # ensure glossary will be available in package doc scope | ||||
| app.connect("source-read", add_glossary_to_index) | app.connect("source-read", add_glossary_to_index) | ||||
| # suppress some httpdomain warnings in non web packages | # suppress some httpdomain warnings in non web packages | ||||
| if not any([pattern in app.srcdir for pattern in ("swh-web", "DWAPPS")]): | if not any([pattern in app.srcdir for pattern in ("swh-web", "DWAPPS")]): | ||||
| # filter out httpdomain unresolved reference warnings | # filter out httpdomain unresolved reference warnings | ||||
| # to not consider them as errors when using -W option of sphinx-build | # to not consider them as errors when using -W option of sphinx-build | ||||
| class HttpDomainRefWarningFilter(logging.Filter): | class HttpDomainRefWarningFilter(logging.Filter): | ||||
| def filter(self, record: logging.LogRecord) -> bool: | def filter(self, record: logging.LogRecord) -> bool: | ||||
| return not record.msg.startswith("Cannot resolve reference to") | return not record.msg.startswith("Cannot resolve reference to") | ||||
| # insert a custom filter in the warning log handler of sphinx | # insert a custom filter in the warning log handler of sphinx | ||||
| logger.handlers[1].filters.insert(0, HttpDomainRefWarningFilter()) | logger.handlers[1].filters.insert(0, HttpDomainRefWarningFilter()) | ||||