1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
#! /usr/bin/env python3
# Requires Python 3.6+
# pylint: disable=invalid-name
"""Configuration of Sphinx documentation generator."""
import os
import sys
from pathlib import Path
# -- Path setup --------------------------------------------------------------
PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve()
IS_RELEASE_ON_RTD = (
os.getenv('READTHEDOCS', 'False') == 'True'
and os.environ['READTHEDOCS_VERSION_TYPE'] == 'tag'
)
if IS_RELEASE_ON_RTD:
tags: set[str]
# pylint: disable-next=used-before-assignment
tags.add('is_release') # noqa: F821
# Make in-tree extension importable in non-tox setups/envs, like RTD.
# Refs:
# https://github.com/readthedocs/readthedocs.org/issues/6311
# https://github.com/readthedocs/readthedocs.org/issues/7182
sys.path.insert(0, str(PROJECT_ROOT_DIR))
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosectionlabel', # autocreate section targets for refs
'sphinx.ext.doctest',
'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
# Third-party extensions:
'jaraco.packaging.sphinx',
'sphinx_tabs.tabs',
'sphinxcontrib.apidoc',
'sphinxcontrib.towncrier.ext', # provides `.. towncrier-draft-entries::`
# In-tree extensions:
'spelling_stub_ext', # auto-loads `sphinxcontrib.spelling` if installed
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [
'changelog-fragments.d/**', # Towncrier-managed change notes
]
master_doc = 'index'
apidoc_excluded_paths = []
apidoc_extra_args = [
'--implicit-namespaces',
'--private', # include “_private” modules
]
apidoc_module_dir = '../cheroot'
apidoc_module_first = False
apidoc_output_dir = 'pkg'
apidoc_separate_modules = True
apidoc_toc_file = None
spelling_ignore_acronyms = True
spelling_ignore_importable_modules = True
spelling_ignore_pypi_package_names = True
spelling_ignore_python_builtins = True
spelling_ignore_wiki_words = True
spelling_show_suggestions = True
spelling_word_list_filename = [
'spelling_wordlist.txt',
]
github_url = 'https://github.com'
github_repo_org = 'cherrypy'
github_repo_name = 'cheroot'
github_repo_slug = f'{github_repo_org}/{github_repo_name}'
github_repo_url = f'{github_url}/{github_repo_slug}'
cp_github_repo_url = f'{github_url}/{github_repo_org}/cherrypy'
github_sponsors_url = f'{github_url}/sponsors'
extlinks = {
'issue': (f'{github_repo_url}/issues/%s', '#%s'),
'pr': (f'{github_repo_url}/pull/%s', 'PR #%s'),
'commit': (f'{github_repo_url}/commit/%s', '%s'),
'cp-issue': (f'{cp_github_repo_url}/issues/%s', 'CherryPy #%s'),
'cp-pr': (f'{cp_github_repo_url}/pull/%s', 'CherryPy PR #%s'),
'gh': (f'{github_url}/%s', 'GitHub: %s'),
'user': (f'{github_sponsors_url}/%s', '@%s'),
}
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'python2': ('https://docs.python.org/2', None),
# Ref: https://github.com/cherrypy/cherrypy/issues/1872
'cherrypy': (
'https://docs.cherrypy.dev/en/latest',
('https://cherrypy.rtfd.io/en/latest', None),
),
'trustme': ('https://trustme.readthedocs.io/en/latest/', None),
'ddt': ('https://ddt.readthedocs.io/en/latest/', None),
'pyopenssl': ('https://www.pyopenssl.org/en/latest/', None),
'towncrier': ('https://towncrier.rtfd.io/en/latest', None),
}
linkcheck_ignore = [
r'http://localhost:\d+/', # local URLs
r'https://codecov\.io/gh/cherrypy/cheroot/branch/master/graph/badge\.svg',
r'https://github\.com/cherrypy/cheroot/actions', # 404 if no auth
# Too many links to GitHub so they cause
# "429 Client Error: too many requests for url"
# Ref: https://github.com/sphinx-doc/sphinx/issues/7388
r'https://github\.com/cherrypy/cheroot/issues',
r'https://github\.com/cherrypy/cheroot/pull',
r'https://github\.com/cherrypy/cherrypy/issues',
r'https://github\.com/cherrypy/cherrypy/pull',
# Has an ephemeral anchor (line-range) but actual HTML has separate per-
# line anchors.
r'https://github\.com'
r'/python/cpython/blob/c39b52f/Lib/poplib\.py#L297-L302',
r'https://github\.com'
r'/python/cpython/blob/c39b52f/Lib/poplib\.py#user-content-L297-L302',
r'^https://matrix\.to/#', # these render fully on front-end from anchors
]
linkcheck_workers = 25
# -- Options for sphinx.ext.autosectionlabel extension -----------------------
# Ref:
# https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
autosectionlabel_maxdepth = 1 # mitigate Towncrier nested subtitles collision
nitpicky = True
# NOTE: consider having a separate ignore file
# Ref: https://stackoverflow.com/a/30624034/595220
nitpick_ignore = [
('py:const', 'socket.SO_PEERCRED'),
('py:class', '_pyio.BufferedWriter'),
('py:class', '_pyio.BufferedReader'),
('py:class', 'unittest.case.TestCase'),
('py:meth', 'cheroot.connections.ConnectionManager.get_conn'),
# Ref: https://github.com/pyca/pyopenssl/issues/1012
('py:class', 'pyopenssl:OpenSSL.SSL.Context'),
]
# -- Options for towncrier_draft extension -----------------------------------
# or: 'sphinx-version', 'sphinx-release'
towncrier_draft_autoversion_mode = 'draft'
towncrier_draft_include_empty = True
towncrier_draft_working_directory = PROJECT_ROOT_DIR
towncrier_draft_config_path = 'towncrier.toml' # relative to cwd
# Ref:
# * https://github.com/djungelorm/sphinx-tabs/issues/26#issuecomment-422160463
sphinx_tabs_valid_builders = ['linkcheck'] # prevent linkcheck warning
# Ref: https://github.com/python-attrs/attrs/pull/571/files\
# #diff-85987f48f1258d9ee486e3191495582dR82
default_role = 'any'
html_theme = 'furo'
|
