| 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": ("/usr/share/doc/python3-doc/html", "/usr/share/doc/python3-doc/html/objects.inv"), |
| 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() |