Differential D5565 Diff 19887 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 os		import os
from typing import Dict		from typing import Dict

import django		import django
		from sphinx.ext import autodoc

# General information about the project.		# General information about the project.
project = "Software Heritage - Development Documentation"		project = "Software Heritage - Development Documentation"
copyright = "2015-2021 The Software Heritage developers"		copyright = "2015-2021 The Software Heritage developers"
author = "The Software Heritage developers"		author = "The Software Heritage developers"

# -- General configuration ------------------------------------------------		# -- General configuration ------------------------------------------------

Show All 11 Lines	extensions = [
"sphinx_tabs.tabs",		"sphinx_tabs.tabs",
"sphinx_rtd_theme",		"sphinx_rtd_theme",
"sphinx.ext.graphviz",		"sphinx.ext.graphviz",
"sphinx_click.ext",		"sphinx_click.ext",
"myst_parser",		"myst_parser",
"sphinx.ext.todo",		"sphinx.ext.todo",
"sphinx_reredirects",		"sphinx_reredirects",
"swh.docs.sphinx.view_in_phabricator",		"swh.docs.sphinx.view_in_phabricator",

# swh.scheduler inherits some attribute descriptions from celery that use		# swh.scheduler inherits some attribute descriptions from celery that use
# custom crossrefs (eg. :setting:`task_ignore_result`)		# custom crossrefs (eg. :setting:`task_ignore_result`)
"sphinx_celery.setting_crossref",		"sphinx_celery.setting_crossref",
]		]

# Add any paths that contain templates here, relative to this directory.		# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]		templates_path = ["_templates"]

▲ Show 20 Lines • Show All 107 Lines • ▼ Show 20 Lines
autodoc_member_order = "bysource"		autodoc_member_order = "bysource"
autodoc_mock_imports = ["rados"]		autodoc_mock_imports = ["rados"]

modindex_common_prefix = ["swh."]		modindex_common_prefix = ["swh."]

# For the todo extension. Todo and todolist produce output only if this is True		# For the todo extension. Todo and todolist produce output only if this is True
todo_include_todos = True		todo_include_todos = True

		_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_api": (f"{_swh_web_base_url}/api/1/%s", None),
		"swh_web_browse": (f"{_swh_web_base_url}/browse/%s", None),
		}


		class SimpleDocumenter(autodoc.FunctionDocumenter):
		"""
		Custom autodoc directive to inline the docstring of a function
		in a document without the signature header and with no indentation.
		vlorentzUnsubmitted Not Done Inline Actions why do we need this? When does it trigger? vlorentz: why do we need this? When does it trigger?
		anlambertAuthorUnsubmitted Done Inline Actions It is used to embed Web API endpoints docstrings into sphinx documentation for swh-web URLs, for instance the Web API ones. It enables to remove the header with the endpoint implementation function signature and remove indentation. This will be removed at some point but `swh-web` still needs it at the moment. anlambert: It is used to embed Web API endpoints docstrings into sphinx documentation for swh-web URLs…
		vlorentzUnsubmitted Not Done Inline Actions Thx. Can you add this explaination in the docstring? vlorentz: Thx. Can you add this explaination in the docstring?

		Example of use::

		.. autosimple:: swh.web.api.views.directory.api_directory
		"""

		objtype = "simple"
		# ensure the priority is lesser than the base FunctionDocumenter
		# to avoid side effects with autodoc processing
		priority = -1

		# do not indent the content
		content_indent = ""

		# do not add a header to the docstring
		def add_directive_header(self, sig):
		pass


# XXX Kill this ASA this PR is accepted and released		# XXX Kill this ASA this PR is accepted and released
# https://github.com/sphinx-contrib/httpdomain/pull/19		# https://github.com/sphinx-contrib/httpdomain/pull/19
def register_routingtable_as_label(app, document):		def register_routingtable_as_label(app, document):
from sphinx.locale import _ # noqa		from sphinx.locale import _ # noqa

labels = app.env.domaindata["std"]["labels"]		labels = app.env.domaindata["std"]["labels"]
labels["routingtable"] = "http-routingtable", "", _("HTTP Routing Table")		labels["routingtable"] = "http-routingtable", "", _("HTTP Routing Table")
anonlabels = app.env.domaindata["std"]["anonlabels"]		anonlabels = app.env.domaindata["std"]["anonlabels"]
anonlabels["routingtable"] = "http-routingtable", ""		anonlabels["routingtable"] = "http-routingtable", ""


		def setup(app):
# hack to set the adequate django settings when building global swh doc		# hack to set the adequate django settings when building global swh doc
# to avoid autodoc build errors		# to avoid autodoc build errors
def setup(app):
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "swh.docs.django_settings")		os.environ.setdefault("DJANGO_SETTINGS_MODULE", "swh.docs.django_settings")
django.setup()		django.setup()

		# add autosimple directive (used in swh-web)
		app.add_autodocumenter(SimpleDocumenter)
		# set an environment variable indicating we are currently building
		# the documentation
		os.environ["SWH_DOC_BUILD"] = "1"

		# 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)