1 #
2 # Python documentation build configuration file
3 #
4 # This file is execfile()d with the current directory set to its containing dir.
5 #
6 # The contents of this file are pickled, so don't put values in the namespace
7 # that aren't pickleable (module imports are okay, they're removed automatically).
8
9 import sys, os, time
10 sys.path.append(os.path.abspath('tools/extensions'))
11 sys.path.append(os.path.abspath('includes'))
12
13 # General configuration
14 # ---------------------
15
16 extensions = [
17 'asdl_highlight',
18 'c_annotations',
19 'escape4chm',
20 'glossary_search',
21 'peg_highlight',
22 'pyspecific',
23 'sphinx.ext.coverage',
24 'sphinx.ext.doctest',
25 ]
26
27 # Skip if downstream redistributors haven't installed it
28 try:
29 import sphinxext.opengraph
30 except ImportError:
31 pass
32 else:
33 extensions.append('sphinxext.opengraph')
34
35
36 doctest_global_setup = '''
37 try:
38 import _tkinter
39 except ImportError:
40 _tkinter = None
41 '''
42
43 manpages_url = 'https://manpages.debian.org/{path}'
44
45 # General substitutions.
46 project = 'Python'
47 copyright = '2001-%s, Python Software Foundation' % time.strftime('%Y')
48
49 # We look for the Include/patchlevel.h file in the current Python source tree
50 # and replace the values accordingly.
51 import patchlevel
52 version, release = patchlevel.get_version_info()
53
54 # There are two options for replacing |today|: either, you set today to some
55 # non-false value, then it is used:
56 today = ''
57 # Else, today_fmt is used as the format for a strftime call.
58 today_fmt = '%B %d, %Y'
59
60 # By default, highlight as Python 3.
61 highlight_language = 'python3'
62
63 # Minimum version of sphinx required
64 needs_sphinx = '4.2'
65
66 # Ignore any .rst files in the includes/ directory;
67 # they're embedded in pages but not rendered individually.
68 # Ignore any .rst files in the venv/ directory.
69 exclude_patterns = ['includes/*.rst', 'venv/*', 'README.rst']
70 venvdir = os.getenv('VENVDIR')
71 if venvdir is not None:
72 exclude_patterns.append(venvdir + '/*')
73
74 nitpick_ignore = [
75 # Standard C functions
76 ('c:func', 'calloc'),
77 ('c:func', 'dlopen'),
78 ('c:func', 'exec'),
79 ('c:func', 'fcntl'),
80 ('c:func', 'fork'),
81 ('c:func', 'free'),
82 ('c:func', 'gmtime'),
83 ('c:func', 'localtime'),
84 ('c:func', 'main'),
85 ('c:func', 'malloc'),
86 ('c:func', 'printf'),
87 ('c:func', 'realloc'),
88 ('c:func', 'snprintf'),
89 ('c:func', 'sprintf'),
90 ('c:func', 'stat'),
91 ('c:func', 'system'),
92 ('c:func', 'vsnprintf'),
93 # Standard C types
94 ('c:type', 'FILE'),
95 ('c:type', 'int64_t'),
96 ('c:type', 'intmax_t'),
97 ('c:type', 'off_t'),
98 ('c:type', 'ptrdiff_t'),
99 ('c:type', 'siginfo_t'),
100 ('c:type', 'size_t'),
101 ('c:type', 'ssize_t'),
102 ('c:type', 'time_t'),
103 ('c:type', 'uint64_t'),
104 ('c:type', 'uintmax_t'),
105 ('c:type', 'uintptr_t'),
106 ('c:type', 'va_list'),
107 ('c:type', 'wchar_t'),
108 # Standard C structures
109 ('c:struct', 'in6_addr'),
110 ('c:struct', 'in_addr'),
111 ('c:struct', 'stat'),
112 ('c:struct', 'statvfs'),
113 # Standard C macros
114 ('c:macro', 'LLONG_MAX'),
115 ('c:macro', 'LLONG_MIN'),
116 ('c:macro', 'LONG_MAX'),
117 ('c:macro', 'LONG_MIN'),
118 # Standard C variables
119 ('c:data', 'errno'),
120 # Standard environment variables
121 ('envvar', 'BROWSER'),
122 ('envvar', 'COLUMNS'),
123 ('envvar', 'COMSPEC'),
124 ('envvar', 'DISPLAY'),
125 ('envvar', 'HOME'),
126 ('envvar', 'HOMEDRIVE'),
127 ('envvar', 'HOMEPATH'),
128 ('envvar', 'IDLESTARTUP'),
129 ('envvar', 'LANG'),
130 ('envvar', 'LANGUAGE'),
131 ('envvar', 'LC_ALL'),
132 ('envvar', 'LC_CTYPE'),
133 ('envvar', 'LC_COLLATE'),
134 ('envvar', 'LC_MESSAGES'),
135 ('envvar', 'LC_MONETARY'),
136 ('envvar', 'LC_NUMERIC'),
137 ('envvar', 'LC_TIME'),
138 ('envvar', 'LINES'),
139 ('envvar', 'LOGNAME'),
140 ('envvar', 'PAGER'),
141 ('envvar', 'PATH'),
142 ('envvar', 'PATHEXT'),
143 ('envvar', 'SOURCE_DATE_EPOCH'),
144 ('envvar', 'TEMP'),
145 ('envvar', 'TERM'),
146 ('envvar', 'TMP'),
147 ('envvar', 'TMPDIR'),
148 ('envvar', 'TZ'),
149 ('envvar', 'USER'),
150 ('envvar', 'USERNAME'),
151 ('envvar', 'USERPROFILE'),
152 # Deprecated function that was never documented:
153 ('py:func', 'getargspec'),
154 ('py:func', 'inspect.getargspec'),
155 ]
156
157 # Temporary undocumented names.
158 # In future this list must be empty.
159 nitpick_ignore += [
160 # C API: Standard Python exception classes
161 ('c:data', 'PyExc_ArithmeticError'),
162 ('c:data', 'PyExc_AssertionError'),
163 ('c:data', 'PyExc_AttributeError'),
164 ('c:data', 'PyExc_BaseException'),
165 ('c:data', 'PyExc_BlockingIOError'),
166 ('c:data', 'PyExc_BrokenPipeError'),
167 ('c:data', 'PyExc_BufferError'),
168 ('c:data', 'PyExc_ChildProcessError'),
169 ('c:data', 'PyExc_ConnectionAbortedError'),
170 ('c:data', 'PyExc_ConnectionError'),
171 ('c:data', 'PyExc_ConnectionRefusedError'),
172 ('c:data', 'PyExc_ConnectionResetError'),
173 ('c:data', 'PyExc_EOFError'),
174 ('c:data', 'PyExc_Exception'),
175 ('c:data', 'PyExc_FileExistsError'),
176 ('c:data', 'PyExc_FileNotFoundError'),
177 ('c:data', 'PyExc_FloatingPointError'),
178 ('c:data', 'PyExc_GeneratorExit'),
179 ('c:data', 'PyExc_ImportError'),
180 ('c:data', 'PyExc_IndentationError'),
181 ('c:data', 'PyExc_IndexError'),
182 ('c:data', 'PyExc_InterruptedError'),
183 ('c:data', 'PyExc_IsADirectoryError'),
184 ('c:data', 'PyExc_KeyboardInterrupt'),
185 ('c:data', 'PyExc_KeyError'),
186 ('c:data', 'PyExc_LookupError'),
187 ('c:data', 'PyExc_MemoryError'),
188 ('c:data', 'PyExc_ModuleNotFoundError'),
189 ('c:data', 'PyExc_NameError'),
190 ('c:data', 'PyExc_NotADirectoryError'),
191 ('c:data', 'PyExc_NotImplementedError'),
192 ('c:data', 'PyExc_OSError'),
193 ('c:data', 'PyExc_OverflowError'),
194 ('c:data', 'PyExc_PermissionError'),
195 ('c:data', 'PyExc_ProcessLookupError'),
196 ('c:data', 'PyExc_RecursionError'),
197 ('c:data', 'PyExc_ReferenceError'),
198 ('c:data', 'PyExc_RuntimeError'),
199 ('c:data', 'PyExc_StopAsyncIteration'),
200 ('c:data', 'PyExc_StopIteration'),
201 ('c:data', 'PyExc_SyntaxError'),
202 ('c:data', 'PyExc_SystemError'),
203 ('c:data', 'PyExc_SystemExit'),
204 ('c:data', 'PyExc_TabError'),
205 ('c:data', 'PyExc_TimeoutError'),
206 ('c:data', 'PyExc_TypeError'),
207 ('c:data', 'PyExc_UnboundLocalError'),
208 ('c:data', 'PyExc_UnicodeDecodeError'),
209 ('c:data', 'PyExc_UnicodeEncodeError'),
210 ('c:data', 'PyExc_UnicodeError'),
211 ('c:data', 'PyExc_UnicodeTranslateError'),
212 ('c:data', 'PyExc_ValueError'),
213 ('c:data', 'PyExc_ZeroDivisionError'),
214 # C API: Standard Python warning classes
215 ('c:data', 'PyExc_BytesWarning'),
216 ('c:data', 'PyExc_DeprecationWarning'),
217 ('c:data', 'PyExc_FutureWarning'),
218 ('c:data', 'PyExc_ImportWarning'),
219 ('c:data', 'PyExc_PendingDeprecationWarning'),
220 ('c:data', 'PyExc_ResourceWarning'),
221 ('c:data', 'PyExc_RuntimeWarning'),
222 ('c:data', 'PyExc_SyntaxWarning'),
223 ('c:data', 'PyExc_UnicodeWarning'),
224 ('c:data', 'PyExc_UserWarning'),
225 ('c:data', 'PyExc_Warning'),
226 # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
227 # be resolved, as the method is currently undocumented. For context, see
228 # https://github.com/python/cpython/pull/103289.
229 ('py:meth', '_SubParsersAction.add_parser'),
230 ]
231
232 # gh-106948: Copy standard C types declared in the "c:type" domain to the
233 # "c:identifier" domain, since "c:function" markup looks for types in the
234 # "c:identifier" domain. Use list() to not iterate on items which are being
235 # added
236 for role, name in list(nitpick_ignore):
237 if role == 'c:type':
238 nitpick_ignore.append(('c:identifier', name))
239 del role, name
240
241 # Disable Docutils smartquotes for several translations
242 smartquotes_excludes = {
243 'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'], 'builders': ['man', 'text'],
244 }
245
246 # Avoid a warning with Sphinx >= 2.0
247 master_doc = 'contents'
248
249 # Allow translation of index directives
250 gettext_additional_targets = [
251 'index',
252 ]
253
254 # Options for HTML output
255 # -----------------------
256
257 # Use our custom theme.
258 html_theme = 'python_docs_theme'
259 html_theme_path = ['tools']
260 html_theme_options = {
261 'collapsiblesidebar': True,
262 'issues_url': '/bugs.html',
263 'license_url': '/license.html',
264 'root_include_title': False # We use the version switcher instead.
265 }
266
267 # Override stylesheet fingerprinting for Windows CHM htmlhelp to fix GH-91207
268 # https://github.com/python/cpython/issues/91207
269 if any('htmlhelp' in arg for arg in sys.argv):
270 html_style = 'pydoctheme.css'
271 print("\nWARNING: Windows CHM Help is no longer supported.")
272 print("It may be removed in the future\n")
273
274 # Short title used e.g. for <title> HTML tags.
275 html_short_title = '%s Documentation' % release
276
277 # Deployment preview information
278 # (See .readthedocs.yml and https://docs.readthedocs.io/en/stable/reference/environment-variables.html)
279 repository_url = os.getenv("READTHEDOCS_GIT_CLONE_URL")
280 html_context = {
281 "is_deployment_preview": os.getenv("READTHEDOCS_VERSION_TYPE") == "external",
282 "repository_url": repository_url.removesuffix(".git") if repository_url else None,
283 "pr_id": os.getenv("READTHEDOCS_VERSION")
284 }
285
286 # This 'Last updated on:' timestamp is inserted at the bottom of every page.
287 html_last_updated_fmt = time.strftime('%b %d, %Y (%H:%M UTC)', time.gmtime())
288
289 # Path to find HTML templates.
290 templates_path = ['tools/templates']
291
292 # Custom sidebar templates, filenames relative to this file.
293 html_sidebars = {
294 # Defaults taken from https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
295 # Removes the quick search block
296 '**': ['localtoc.html', 'relations.html', 'customsourcelink.html'],
297 'index': ['indexsidebar.html'],
298 }
299
300 # Additional templates that should be rendered to pages.
301 html_additional_pages = {
302 'download': 'download.html',
303 'index': 'indexcontent.html',
304 }
305
306 # Output an OpenSearch description file.
307 html_use_opensearch = 'https://docs.python.org/' + version
308
309 # Additional static files.
310 html_static_path = ['_static', 'tools/static']
311
312 # Output file base name for HTML help builder.
313 htmlhelp_basename = 'python' + release.replace('.', '')
314
315 # Split the index
316 html_split_index = True
317
318
319 # Options for LaTeX output
320 # ------------------------
321
322 latex_engine = 'xelatex'
323
324 # Get LaTeX to handle Unicode correctly
325 latex_elements = {
326 }
327
328 # Additional stuff for the LaTeX preamble.
329 latex_elements['preamble'] = r'''
330 \authoraddress{
331 \sphinxstrong{Python Software Foundation}\\
332 Email: \sphinxemail{docs@python.org}
333 }
334 \let\Verbatim=\OriginalVerbatim
335 \let\endVerbatim=\endOriginalVerbatim
336 \setcounter{tocdepth}{2}
337 '''
338
339 # The paper size ('letter' or 'a4').
340 latex_elements['papersize'] = 'a4'
341
342 # The font size ('10pt', '11pt' or '12pt').
343 latex_elements['pointsize'] = '10pt'
344
345 # Grouping the document tree into LaTeX files. List of tuples
346 # (source start file, target name, title, author, document class [howto/manual]).
347 _stdauthor = 'Guido van Rossum and the Python development team'
348 latex_documents = [
349 ('c-api/index', 'c-api.tex',
350 'The Python/C API', _stdauthor, 'manual'),
351 ('extending/index', 'extending.tex',
352 'Extending and Embedding Python', _stdauthor, 'manual'),
353 ('installing/index', 'installing.tex',
354 'Installing Python Modules', _stdauthor, 'manual'),
355 ('library/index', 'library.tex',
356 'The Python Library Reference', _stdauthor, 'manual'),
357 ('reference/index', 'reference.tex',
358 'The Python Language Reference', _stdauthor, 'manual'),
359 ('tutorial/index', 'tutorial.tex',
360 'Python Tutorial', _stdauthor, 'manual'),
361 ('using/index', 'using.tex',
362 'Python Setup and Usage', _stdauthor, 'manual'),
363 ('faq/index', 'faq.tex',
364 'Python Frequently Asked Questions', _stdauthor, 'manual'),
365 ('whatsnew/' + version, 'whatsnew.tex',
366 'What\'s New in Python', 'A. M. Kuchling', 'howto'),
367 ]
368 # Collect all HOWTOs individually
369 latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex',
370 '', _stdauthor, 'howto')
371 for fn in os.listdir('howto')
372 if fn.endswith('.rst') and fn != 'index.rst')
373
374 # Documents to append as an appendix to all manuals.
375 latex_appendices = ['glossary', 'about', 'license', 'copyright']
376
377 # Options for Epub output
378 # -----------------------
379
380 epub_author = 'Python Documentation Authors'
381 epub_publisher = 'Python Software Foundation'
382
383 # Options for the coverage checker
384 # --------------------------------
385
386 # The coverage checker will ignore all modules/functions/classes whose names
387 # match any of the following regexes (using re.match).
388 coverage_ignore_modules = [
389 r'[T|t][k|K]',
390 r'Tix',
391 r'distutils.*',
392 ]
393
394 coverage_ignore_functions = [
395 'test($|_)',
396 ]
397
398 coverage_ignore_classes = [
399 ]
400
401 # Glob patterns for C source files for C API coverage, relative to this directory.
402 coverage_c_path = [
403 '../Include/*.h',
404 ]
405
406 # Regexes to find C items in the source files.
407 coverage_c_regexes = {
408 'cfunction': (r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'),
409 'data': (r'^PyAPI_DATA\(.*\)\s+([^_][\w_]+)'),
410 'macro': (r'^#define ([^_][\w_]+)\(.*\)[\s|\\]'),
411 }
412
413 # The coverage checker will ignore all C items whose names match these regexes
414 # (using re.match) -- the keys must be the same as in coverage_c_regexes.
415 coverage_ignore_c_items = {
416 # 'cfunction': [...]
417 }
418
419
420 # Options for the link checker
421 # ----------------------------
422
423 linkcheck_allowed_redirects = {
424 # bpo-NNNN -> BPO -> GH Issues
425 r'https://bugs.python.org/issue\?@action=redirect&bpo=\d+': r'https://github.com/python/cpython/issues/\d+',
426 # GH-NNNN used to refer to pull requests
427 r'https://github.com/python/cpython/issues/\d+': r'https://github.com/python/cpython/pull/\d+',
428 # :source:`something` linking files in the repository
429 r'https://github.com/python/cpython/tree/.*': 'https://github.com/python/cpython/blob/.*',
430 # Intentional HTTP use at Misc/NEWS.d/3.5.0a1.rst
431 r'http://www.python.org/$': 'https://www.python.org/$',
432 # Used in license page, keep as is
433 r'https://www.zope.org/': r'https://www.zope.dev/',
434 # Microsoft's redirects to learn.microsoft.com
435 r'https://msdn.microsoft.com/.*': 'https://learn.microsoft.com/.*',
436 r'https://docs.microsoft.com/.*': 'https://learn.microsoft.com/.*',
437 r'https://go.microsoft.com/fwlink/\?LinkID=\d+': 'https://learn.microsoft.com/.*',
438 # Language redirects
439 r'https://toml.io': 'https://toml.io/en/',
440 r'https://www.redhat.com': 'https://www.redhat.com/en',
441 # Other redirects
442 r'https://www.boost.org/libs/.+': r'https://www.boost.org/doc/libs/\d_\d+_\d/.+',
443 r'https://support.microsoft.com/en-us/help/\d+': 'https://support.microsoft.com/en-us/topic/.+',
444 r'https://perf.wiki.kernel.org$': 'https://perf.wiki.kernel.org/index.php/Main_Page',
445 r'https://www.sqlite.org': 'https://www.sqlite.org/index.html',
446 r'https://mitpress.mit.edu/sicp$': 'https://mitpress.mit.edu/9780262510875/structure-and-interpretation-of-computer-programs/',
447 r'https://www.python.org/psf/': 'https://www.python.org/psf-landing/',
448 }
449
450 linkcheck_anchors_ignore = [
451 # ignore anchors that start with a '/', e.g. Wikipedia media files:
452 # https://en.wikipedia.org/wiki/Walrus#/media/File:Pacific_Walrus_-_Bull_(8247646168).jpg
453 r'\/.*',
454 ]
455
456 linkcheck_ignore = [
457 # The crawler gets "Anchor not found"
458 r'https://developer.apple.com/documentation/.+?#.*',
459 r'https://devguide.python.org.+?/#.*',
460 r'https://github.com.+?#.*',
461 # Robot crawlers not allowed: "403 Client Error: Forbidden"
462 r'https://support.enthought.com/hc/.*',
463 # SSLError CertificateError, even though it is valid
464 r'https://unix.org/version2/whatsnew/lp64_wp.html',
465 ]
466
467
468 # Options for extensions
469 # ----------------------
470
471 # Relative filename of the data files
472 refcount_file = 'data/refcounts.dat'
473 stable_abi_file = 'data/stable_abi.dat'
474
475 # sphinxext-opengraph config
476 ogp_site_url = 'https://docs.python.org/3/'
477 ogp_site_name = 'Python documentation'
478 ogp_image = '_static/og-image.png'
479 ogp_custom_meta_tags = [
480 '<meta property="og:image:width" content="200" />',
481 '<meta property="og:image:height" content="200" />',
482 '<meta name="theme-color" content="#3776ab" />',
483 ]