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