Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | # |
| 2 | # Python documentation build configuration file |
| 3 | # |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 4 | # This file is execfile()d with the current directory set to its containing dir. |
| 5 | # |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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). |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 8 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 9 | import sys, os, time |
Georg Brandl | e039029 | 2014-10-29 08:07:37 +0100 | [diff] [blame] | 10 | sys.path.append(os.path.abspath('tools/extensions')) |
Marco Buttu | 909a6f6 | 2017-03-18 17:59:33 +0100 | [diff] [blame] | 11 | sys.path.append(os.path.abspath('includes')) |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 12 | |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 13 | # General configuration |
| 14 | # --------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | |
Georg Brandl | 5c01d99 | 2013-10-12 19:54:30 +0200 | [diff] [blame] | 16 | extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest', |
Batuhan Taskaya | b7a78ca | 2020-05-07 23:57:26 +0300 | [diff] [blame] | 17 | 'pyspecific', 'c_annotations', 'escape4chm', |
| 18 | 'asdl_highlight'] |
Christian Heimes | 2685563 | 2008-01-27 23:50:43 +0000 | [diff] [blame] | 19 | |
Stéphane Wirtel | 859c068 | 2018-10-12 09:51:05 +0200 | [diff] [blame] | 20 | |
| 21 | doctest_global_setup = ''' |
| 22 | try: |
| 23 | import _tkinter |
| 24 | except ImportError: |
| 25 | _tkinter = None |
| 26 | ''' |
Batuhan Taşkaya | eab9965 | 2019-05-19 00:53:53 +0300 | [diff] [blame] | 27 | |
| 28 | manpages_url = 'https://manpages.debian.org/{path}' |
| 29 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 30 | # General substitutions. |
| 31 | project = 'Python' |
Berker Peksag | 2ec1bee | 2016-04-24 03:21:13 +0300 | [diff] [blame] | 32 | copyright = '2001-%s, Python Software Foundation' % time.strftime('%Y') |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 33 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 34 | # We look for the Include/patchlevel.h file in the current Python source tree |
| 35 | # and replace the values accordingly. |
| 36 | import patchlevel |
| 37 | version, release = patchlevel.get_version_info() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
| 39 | # There are two options for replacing |today|: either, you set today to some |
| 40 | # non-false value, then it is used: |
| 41 | today = '' |
| 42 | # Else, today_fmt is used as the format for a strftime call. |
| 43 | today_fmt = '%B %d, %Y' |
| 44 | |
Georg Brandl | 6406370 | 2008-09-09 19:10:58 +0000 | [diff] [blame] | 45 | # By default, highlight as Python 3. |
| 46 | highlight_language = 'python3' |
| 47 | |
Anthony Sottile | a16ab00 | 2019-02-15 18:41:15 -0500 | [diff] [blame] | 48 | # Minimum version of sphinx required |
| 49 | needs_sphinx = '1.8' |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 50 | |
Senthil Kumaran | 889f914 | 2016-06-04 22:22:26 -0700 | [diff] [blame] | 51 | # Ignore any .rst files in the venv/ directory. |
Julien Palard | 73e0549 | 2019-08-26 08:11:43 +0200 | [diff] [blame] | 52 | exclude_patterns = ['venv/*', 'README.rst'] |
| 53 | venvdir = os.getenv('VENVDIR') |
| 54 | if venvdir is not None: |
| 55 | exclude_patterns.append(venvdir + '/*') |
Brett Cannon | 9b16666 | 2015-03-30 15:35:37 -0400 | [diff] [blame] | 56 | |
Adrian Liaw | c03bf0a | 2018-11-05 05:04:51 +0800 | [diff] [blame] | 57 | # Disable Docutils smartquotes for several translations |
| 58 | smartquotes_excludes = { |
| 59 | 'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'], 'builders': ['man', 'text'], |
| 60 | } |
| 61 | |
Jean-François B | fc8284e | 2018-12-22 23:31:08 +0100 | [diff] [blame] | 62 | # Avoid a warning with Sphinx >= 2.0 |
| 63 | master_doc = 'contents' |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 64 | |
| 65 | # Options for HTML output |
| 66 | # ----------------------- |
| 67 | |
Georg Brandl | 9a333a6 | 2014-10-29 08:04:27 +0100 | [diff] [blame] | 68 | # Use our custom theme. |
Jon Wayne Parrott | bf63e8d | 2018-03-01 13:02:50 -0800 | [diff] [blame] | 69 | html_theme = 'python_docs_theme' |
Ned Deily | 14366f3 | 2014-09-30 18:41:37 -0700 | [diff] [blame] | 70 | html_theme_path = ['tools'] |
Jon Wayne Parrott | bf63e8d | 2018-03-01 13:02:50 -0800 | [diff] [blame] | 71 | html_theme_options = { |
| 72 | 'collapsiblesidebar': True, |
| 73 | 'issues_url': 'https://docs.python.org/3/bugs.html', |
| 74 | 'root_include_title': False # We use the version switcher instead. |
| 75 | } |
Georg Brandl | a074523 | 2010-07-30 11:31:03 +0000 | [diff] [blame] | 76 | |
Georg Brandl | 9a333a6 | 2014-10-29 08:04:27 +0100 | [diff] [blame] | 77 | # Short title used e.g. for <title> HTML tags. |
Georg Brandl | ab71214 | 2012-03-25 20:31:57 +0200 | [diff] [blame] | 78 | html_short_title = '%s Documentation' % release |
| 79 | |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 80 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
| 81 | # using the given strftime format. |
| 82 | html_last_updated_fmt = '%b %d, %Y' |
| 83 | |
Georg Brandl | 9a333a6 | 2014-10-29 08:04:27 +0100 | [diff] [blame] | 84 | # Path to find HTML templates. |
Georg Brandl | a1f8486 | 2014-10-29 08:11:46 +0100 | [diff] [blame] | 85 | templates_path = ['tools/templates'] |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 86 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 87 | # Custom sidebar templates, filenames relative to this file. |
| 88 | html_sidebars = { |
Zachary Ware | a3090a4 | 2016-09-09 13:11:27 -0700 | [diff] [blame] | 89 | # Defaults taken from http://www.sphinx-doc.org/en/stable/config.html#confval-html_sidebars |
| 90 | # Removes the quick search block |
| 91 | '**': ['localtoc.html', 'relations.html', 'customsourcelink.html'], |
| 92 | 'index': ['indexsidebar.html'], |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 93 | } |
| 94 | |
| 95 | # Additional templates that should be rendered to pages. |
| 96 | html_additional_pages = { |
Georg Brandl | 45832ea | 2008-03-12 08:52:43 +0000 | [diff] [blame] | 97 | 'download': 'download.html', |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 98 | 'index': 'indexcontent.html', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 99 | } |
| 100 | |
Georg Brandl | e757005 | 2008-05-03 20:52:18 +0000 | [diff] [blame] | 101 | # Output an OpenSearch description file. |
Georg Brandl | e73778c | 2014-10-29 08:36:35 +0100 | [diff] [blame] | 102 | html_use_opensearch = 'https://docs.python.org/' + version |
Georg Brandl | e757005 | 2008-05-03 20:52:18 +0000 | [diff] [blame] | 103 | |
| 104 | # Additional static files. |
Georg Brandl | 97e9ec6 | 2014-09-30 22:51:30 +0200 | [diff] [blame] | 105 | html_static_path = ['tools/static'] |
Georg Brandl | e757005 | 2008-05-03 20:52:18 +0000 | [diff] [blame] | 106 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 107 | # Output file base name for HTML help builder. |
Christian Heimes | b558a2e | 2008-03-02 22:46:37 +0000 | [diff] [blame] | 108 | htmlhelp_basename = 'python' + release.replace('.', '') |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 109 | |
Amaury Forgeot d'Arc | 35c8658 | 2008-06-17 21:11:29 +0000 | [diff] [blame] | 110 | # Split the index |
| 111 | html_split_index = True |
| 112 | |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 113 | |
| 114 | # Options for LaTeX output |
| 115 | # ------------------------ |
| 116 | |
Julien Palard | 7324b5c | 2017-12-02 23:24:39 +0100 | [diff] [blame] | 117 | latex_engine = 'xelatex' |
| 118 | |
Ryan Gonzalez | e7ffb99 | 2017-02-10 22:47:37 -0600 | [diff] [blame] | 119 | # Get LaTeX to handle Unicode correctly |
François Magimel | da9b4cf | 2017-09-22 19:16:57 +0200 | [diff] [blame] | 120 | latex_elements = { |
François Magimel | da9b4cf | 2017-09-22 19:16:57 +0200 | [diff] [blame] | 121 | } |
Ryan Gonzalez | e7ffb99 | 2017-02-10 22:47:37 -0600 | [diff] [blame] | 122 | |
| 123 | # Additional stuff for the LaTeX preamble. |
| 124 | latex_elements['preamble'] = r''' |
| 125 | \authoraddress{ |
François Magimel | da9b4cf | 2017-09-22 19:16:57 +0200 | [diff] [blame] | 126 | \sphinxstrong{Python Software Foundation}\\ |
| 127 | Email: \sphinxemail{docs@python.org} |
Ryan Gonzalez | e7ffb99 | 2017-02-10 22:47:37 -0600 | [diff] [blame] | 128 | } |
| 129 | \let\Verbatim=\OriginalVerbatim |
| 130 | \let\endVerbatim=\endOriginalVerbatim |
Cheryl Sabella | a4ba8a3 | 2020-02-18 18:01:15 -0500 | [diff] [blame] | 131 | \setcounter{tocdepth}{2} |
Ryan Gonzalez | e7ffb99 | 2017-02-10 22:47:37 -0600 | [diff] [blame] | 132 | ''' |
| 133 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 134 | # The paper size ('letter' or 'a4'). |
Ryan Gonzalez | e7ffb99 | 2017-02-10 22:47:37 -0600 | [diff] [blame] | 135 | latex_elements['papersize'] = 'a4' |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 136 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 137 | # The font size ('10pt', '11pt' or '12pt'). |
François Magimel | da9b4cf | 2017-09-22 19:16:57 +0200 | [diff] [blame] | 138 | latex_elements['pointsize'] = '10pt' |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 139 | |
| 140 | # Grouping the document tree into LaTeX files. List of tuples |
| 141 | # (source start file, target name, title, author, document class [howto/manual]). |
Georg Brandl | 9ab33ea | 2014-10-29 08:14:04 +0100 | [diff] [blame] | 142 | _stdauthor = r'Guido van Rossum\\and the Python development team' |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 143 | latex_documents = [ |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 144 | ('c-api/index', 'c-api.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 145 | 'The Python/C API', _stdauthor, 'manual'), |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 146 | ('distributing/index', 'distributing.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 147 | 'Distributing Python Modules', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 148 | ('extending/index', 'extending.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 149 | 'Extending and Embedding Python', _stdauthor, 'manual'), |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 150 | ('installing/index', 'installing.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 151 | 'Installing Python Modules', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 152 | ('library/index', 'library.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 153 | 'The Python Library Reference', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 154 | ('reference/index', 'reference.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 155 | 'The Python Language Reference', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 156 | ('tutorial/index', 'tutorial.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 157 | 'Python Tutorial', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 158 | ('using/index', 'using.tex', |
Georg Brandl | 8d58216 | 2010-09-03 22:33:27 +0000 | [diff] [blame] | 159 | 'Python Setup and Usage', _stdauthor, 'manual'), |
Georg Brandl | e5b5ff4 | 2010-11-12 06:19:48 +0000 | [diff] [blame] | 160 | ('faq/index', 'faq.tex', |
| 161 | 'Python Frequently Asked Questions', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 162 | ('whatsnew/' + version, 'whatsnew.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 163 | 'What\'s New in Python', 'A. M. Kuchling', 'howto'), |
| 164 | ] |
| 165 | # Collect all HOWTOs individually |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 166 | latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex', |
Benjamin Peterson | f608c61 | 2008-11-16 18:33:53 +0000 | [diff] [blame] | 167 | '', _stdauthor, 'howto') |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 168 | for fn in os.listdir('howto') |
| 169 | if fn.endswith('.rst') and fn != 'index.rst') |
| 170 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 171 | # Documents to append as an appendix to all manuals. |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 172 | latex_appendices = ['glossary', 'about', 'license', 'copyright'] |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 173 | |
Senthil Kumaran | cbe6356 | 2016-01-08 01:01:56 -0800 | [diff] [blame] | 174 | # Options for Epub output |
| 175 | # ----------------------- |
| 176 | |
| 177 | epub_author = 'Python Documentation Authors' |
| 178 | epub_publisher = 'Python Software Foundation' |
Georg Brandl | 9a333a6 | 2014-10-29 08:04:27 +0100 | [diff] [blame] | 179 | |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 180 | # Options for the coverage checker |
| 181 | # -------------------------------- |
| 182 | |
| 183 | # The coverage checker will ignore all modules/functions/classes whose names |
| 184 | # match any of the following regexes (using re.match). |
| 185 | coverage_ignore_modules = [ |
| 186 | r'[T|t][k|K]', |
| 187 | r'Tix', |
| 188 | r'distutils.*', |
| 189 | ] |
| 190 | |
| 191 | coverage_ignore_functions = [ |
| 192 | 'test($|_)', |
| 193 | ] |
| 194 | |
| 195 | coverage_ignore_classes = [ |
| 196 | ] |
| 197 | |
| 198 | # Glob patterns for C source files for C API coverage, relative to this directory. |
| 199 | coverage_c_path = [ |
| 200 | '../Include/*.h', |
| 201 | ] |
| 202 | |
| 203 | # Regexes to find C items in the source files. |
| 204 | coverage_c_regexes = { |
| 205 | 'cfunction': (r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'), |
| 206 | 'data': (r'^PyAPI_DATA\(.*\)\s+([^_][\w_]+)'), |
| 207 | 'macro': (r'^#define ([^_][\w_]+)\(.*\)[\s|\\]'), |
| 208 | } |
| 209 | |
| 210 | # The coverage checker will ignore all C items whose names match these regexes |
| 211 | # (using re.match) -- the keys must be the same as in coverage_c_regexes. |
| 212 | coverage_ignore_c_items = { |
| 213 | # 'cfunction': [...] |
| 214 | } |
Georg Brandl | 9a333a6 | 2014-10-29 08:04:27 +0100 | [diff] [blame] | 215 | |
Georg Brandl | 0ef4966 | 2014-10-29 10:57:01 +0100 | [diff] [blame] | 216 | |
| 217 | # Options for the link checker |
| 218 | # ---------------------------- |
| 219 | |
| 220 | # Ignore certain URLs. |
| 221 | linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+', |
| 222 | # Ignore PEPs for now, they all have permanent redirects. |
| 223 | r'http://www.python.org/dev/peps/pep-\d+'] |
| 224 | |
| 225 | |
Georg Brandl | 9a333a6 | 2014-10-29 08:04:27 +0100 | [diff] [blame] | 226 | # Options for extensions |
| 227 | # ---------------------- |
| 228 | |
| 229 | # Relative filename of the reference count data file. |
| 230 | refcount_file = 'data/refcounts.dat' |