Debian Codegraph @

docs/conf.py

raw ◀ ▶
Source reconstructed at patch state 1 of 2 — not the installed (fully patched) source.
2 Debian patches touch this file
1 from __future__ import annotations
2
3 import re
4 from importlib.machinery import SourceFileLoader
5 from pathlib import Path
6 from typing import TYPE_CHECKING, Any
7
8 from sphinx.domains.python import PythonDomain
9 from sphinx.ext.extlinks import ExternalLinksChecker
10 from truststore import inject_into_ssl
11
12 from tox import __version__
13
14 if TYPE_CHECKING:
15 from docutils.nodes import Element, reference
16 from sphinx.addnodes import pending_xref
17 from sphinx.application import Sphinx
18 from sphinx.builders import Builder
19 from sphinx.environment import BuildEnvironment
20 from sphinx.ext.autodoc import Options
21
22 company, name = "tox-dev", "tox"
23 project = name
24 release, version = __version__, ".".join(__version__.split(".")[:2])
25 copyright = f"{company}" # noqa: A001
26 master_doc = "index"
27 source_suffix = {".rst": "restructuredtext"}
28
29 html_theme = "furo"
30 html_theme_options = {
31 "sidebar_hide_name": True,
32 }
33 html_title, html_last_updated_fmt = "tox", "%Y-%m-%dT%H:%M:%S"
34 html_show_sourcelink = False
35 pygments_style, pygments_dark_style = "sphinx", "monokai"
36 html_static_path, html_css_files = ["_static"], ["custom.css"]
37 html_js_files = ["mermaid-reset.js"]
38 html_logo, html_favicon = "_static/img/tox.svg", "_static/img/toxfavi.ico"
39
40 extensions = [
41 "sphinx.ext.autodoc",
42 "sphinx.ext.autosectionlabel",
43 "sphinx.ext.extlinks",
44 "sphinx.ext.intersphinx",
45 "sphinx_argparse_cli",
46 "sphinx_autodoc_typehints",
47 "sphinx_inline_tabs",
48 "sphinx_copybutton",
49 "sphinx_issues", # :user: and similar roles
50 "sphinxcontrib.mermaid",
51 "sphinxcontrib.towncrier.ext",
52 "sphinx_reredirects",
53 ]
54 mermaid_output_format = "raw"
55 mermaid_d3_zoom = True
56 d3_use_local = "d3.min.js"
57 mermaid_height = "auto"
58
59 exclude_patterns = ["_build", "changelog/*"]
60 autoclass_content, autodoc_member_order, autodoc_typehints = "class", "bysource", "none"
61 autodoc_default_options = {
62 "member-order": "bysource",
63 "undoc-members": True,
64 "show-inheritance": True,
65 }
66 autosectionlabel_prefix_document = True
67
68 extlinks = {
69 "discussion": ("https://github.com/tox-dev/tox/discussions/%s", "#%s"),
70 "gh_repo": ("https://github.com/%s", "%s"),
71 "gh": ("https://github.com/%s", "%s"),
72 }
73 intersphinx_mapping = {
74 "python": ("https://docs.python.org/3", None),
75 "packaging": ("https://packaging.pypa.io/en/latest", None),
76 }
77 nitpicky = True
78 nitpick_ignore = []
79 linkcheck_workers = 10
80 linkcheck_ignore = [
81 re.escape(i)
82 for i in (
83 r"https://github.com/tox-dev/tox/issues/new?title=Trouble+with+development+environment",
84 r"https://porkbun.com/", # has captcha on it that makes it return with 405
85 r"https://opensource.org/license/mit",
86 )
87 ]
88 linkcheck_allowed_redirects = {r"https://github.com/tox-dev/tox/issues/\d+": r"https://github.com/tox-dev/tox/pull/\d+"}
89 extlinks_detect_hardcoded_links = True
90
91 issues_github_path = f"{company}/{name}" # `sphinx-issues` ext
92
93 # Man page configuration
94 man_pages = [("man/tox.1", "tox", "virtualenv-based automation of test activities", [], 1)]
95 man_show_urls = True
96
97 redirects = {
98 "config": "reference/config.html",
99 "cli_interface": "reference/cli.html",
100 "user_guide": "explanation.html",
101 "installation": "how-to/install.html",
102 "howto": "how-to/usage.html",
103 "getting_started": "tutorial/getting-started.html",
104 "plugins": "plugin/index.html",
105 "plugins_api": "plugin/api.html",
106 "plugins/index": "plugin/index.html",
107 "plugins/api": "plugin/api.html",
108 "plugins/getting_started": "plugin/getting_started.html",
109 "plugins/howto": "plugin/howto.html",
110 "upgrading": "index.html",
111 "faq": "index.html",
112 "example/general": "index.html",
113 "example/basic": "index.html",
114 "example/devenv": "index.html",
115 "example/documentation": "index.html",
116 "example/jenkins": "index.html",
117 "example/nose": "index.html",
118 "example/package": "index.html",
119 "example/platform": "index.html",
120 "example/pytest": "index.html",
121 "example/result": "index.html",
122 "example/unittest": "index.html",
123 }
124
125 towncrier_draft_autoversion_mode = "draft"
126 towncrier_draft_include_empty = True
127 towncrier_draft_working_directory = Path(__file__).parent.parent
128
129
130 def process_signature( # noqa: PLR0913
131 app: Sphinx, # noqa: ARG001
132 objtype: str,
133 name: str, # noqa: ARG001
134 obj: Any, # noqa: ARG001
135 options: Options,
136 args: str | None, # noqa: ARG001
137 retann: str | None, # noqa: ARG001
138 ) -> tuple[None, None] | None:
139 # skip-member is not checked for class level docs, so disable via signature processing
140 if objtype == "class" and (exclude := options.get("exclude-members")) and "__init__" in exclude:
141 return None, None
142 return None
143
144
145 def setup(app: Sphinx) -> None:
146 here = Path(__file__).parent
147
148 class PatchedPythonDomain(PythonDomain):
149 def resolve_xref( # noqa: PLR0913
150 self,
151 env: BuildEnvironment,
152 fromdocname: str,
153 builder: Builder,
154 type: str, # noqa: A002
155 target: str,
156 node: pending_xref,
157 contnode: Element,
158 ) -> reference | None:
159 # fixup some wrongly resolved mappings
160 mapping = {
161 "tox.config.of_type.T": "typing.TypeVar", # used by Sphinx bases
162 "tox.config.loader.api.T": "typing.TypeVar", # used by Sphinx bases
163 "tox.config.loader.convert.T": "typing.TypeVar", # used by Sphinx bases
164 "tox.tox_env.installer.T": "typing.TypeVar", # used by Sphinx bases
165 "pathlib._local.Path": "pathlib.Path",
166 }
167 if target in mapping:
168 target = node["reftarget"] = mapping[target]
169 return super().resolve_xref(env, fromdocname, builder, type, target, node, contnode)
170
171 app.connect("autodoc-process-signature", process_signature, priority=400)
172 app.add_domain(PatchedPythonDomain, override=True)
173 tox_cfg = SourceFileLoader("tox_conf", str(here / "tox_conf.py")).load_module().ToxConfig
174 app.add_directive(tox_cfg.name, tox_cfg)
175
176 def check_uri(self: ExternalLinksChecker, refnode: reference) -> None:
177 if refnode.document is not None and refnode.document.attributes["source"].endswith("index.rst"):
178 return None # do not use for the index file
179 return prev_check(self, refnode)
180
181 prev_check = ExternalLinksChecker.check_uri
182 ExternalLinksChecker.check_uri = check_uri # ty: ignore[invalid-assignment] # monkey-patching instance method onto class
183 inject_into_ssl()