Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | # -*- coding: utf-8 -*- |
| 2 | # |
| 3 | # Python documentation build configuration file |
| 4 | # |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 5 | # This file is execfile()d with the current directory set to its containing dir. |
| 6 | # |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | # The contents of this file are pickled, so don't put values in the namespace |
| 8 | # that aren't pickleable (module imports are okay, they're removed automatically). |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 9 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 10 | import sys, os, time |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 11 | sys.path.append(os.path.abspath('tools/sphinxext')) |
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 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 16 | extensions = ['sphinx.ext.refcounting', 'sphinx.ext.coverage', |
Martin v. Löwis | 5680d0c | 2008-04-10 03:06:53 +0000 | [diff] [blame] | 17 | 'sphinx.ext.doctest', 'pyspecific'] |
Georg Brandl | 45832ea | 2008-03-12 08:52:43 +0000 | [diff] [blame] | 18 | templates_path = ['tools/sphinxext'] |
Christian Heimes | 2685563 | 2008-01-27 23:50:43 +0000 | [diff] [blame] | 19 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 20 | # General substitutions. |
| 21 | project = 'Python' |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 22 | copyright = '1990-%s, Python Software Foundation' % time.strftime('%Y') |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 23 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | # The default replacements for |version| and |release|. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 25 | # |
| 26 | # The short X.Y version. |
| 27 | # version = '2.6' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | # The full version, including alpha/beta/rc tags. |
| 29 | # release = '2.6a0' |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 30 | |
| 31 | # We look for the Include/patchlevel.h file in the current Python source tree |
| 32 | # and replace the values accordingly. |
| 33 | import patchlevel |
| 34 | version, release = patchlevel.get_version_info() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | |
| 36 | # There are two options for replacing |today|: either, you set today to some |
| 37 | # non-false value, then it is used: |
| 38 | today = '' |
| 39 | # Else, today_fmt is used as the format for a strftime call. |
| 40 | today_fmt = '%B %d, %Y' |
| 41 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | # List of files that shouldn't be included in the build. |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 43 | unused_docs = [ |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 44 | 'maclib/scrap', |
| 45 | 'library/xmllib', |
| 46 | 'library/xml.etree', |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | ] |
| 48 | |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 49 | # Ignore .rst in Sphinx its self. |
| 50 | exclude_trees = ['tools/sphinx'] |
| 51 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 52 | # Relative filename of the reference count data file. |
| 53 | refcount_file = 'data/refcounts.dat' |
| 54 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | # If true, '()' will be appended to :func: etc. cross-reference text. |
| 56 | add_function_parentheses = True |
| 57 | |
| 58 | # If true, the current module name will be prepended to all description |
| 59 | # unit titles (such as .. function::). |
| 60 | add_module_names = True |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 61 | |
Georg Brandl | 6406370 | 2008-09-09 19:10:58 +0000 | [diff] [blame] | 62 | # By default, highlight as Python 3. |
| 63 | highlight_language = 'python3' |
| 64 | |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 65 | |
| 66 | # Options for HTML output |
| 67 | # ----------------------- |
| 68 | |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 69 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
| 70 | # using the given strftime format. |
| 71 | html_last_updated_fmt = '%b %d, %Y' |
| 72 | |
| 73 | # If true, SmartyPants will be used to convert quotes and dashes to |
| 74 | # typographically correct entities. |
| 75 | html_use_smartypants = True |
| 76 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 77 | # Custom sidebar templates, filenames relative to this file. |
| 78 | html_sidebars = { |
Georg Brandl | 45832ea | 2008-03-12 08:52:43 +0000 | [diff] [blame] | 79 | 'index': 'indexsidebar.html', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 80 | } |
| 81 | |
| 82 | # Additional templates that should be rendered to pages. |
| 83 | html_additional_pages = { |
Georg Brandl | 45832ea | 2008-03-12 08:52:43 +0000 | [diff] [blame] | 84 | 'download': 'download.html', |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 85 | 'index': 'indexcontent.html', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 86 | } |
| 87 | |
Georg Brandl | e757005 | 2008-05-03 20:52:18 +0000 | [diff] [blame] | 88 | # Output an OpenSearch description file. |
Benjamin Peterson | 00f8585 | 2009-10-01 00:10:50 +0000 | [diff] [blame^] | 89 | html_use_opensearch = 'http://docs.python.org/3.1' |
Georg Brandl | e757005 | 2008-05-03 20:52:18 +0000 | [diff] [blame] | 90 | |
| 91 | # Additional static files. |
| 92 | html_static_path = ['tools/sphinxext/static'] |
| 93 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 94 | # Output file base name for HTML help builder. |
Christian Heimes | b558a2e | 2008-03-02 22:46:37 +0000 | [diff] [blame] | 95 | htmlhelp_basename = 'python' + release.replace('.', '') |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 96 | |
Amaury Forgeot d'Arc | 35c8658 | 2008-06-17 21:11:29 +0000 | [diff] [blame] | 97 | # Split the index |
| 98 | html_split_index = True |
| 99 | |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 100 | |
| 101 | # Options for LaTeX output |
| 102 | # ------------------------ |
| 103 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 104 | # The paper size ('letter' or 'a4'). |
| 105 | latex_paper_size = 'a4' |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 106 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 107 | # The font size ('10pt', '11pt' or '12pt'). |
| 108 | latex_font_size = '10pt' |
| 109 | |
| 110 | # Grouping the document tree into LaTeX files. List of tuples |
| 111 | # (source start file, target name, title, author, document class [howto/manual]). |
| 112 | _stdauthor = r'Guido van Rossum\\Fred L. Drake, Jr., editor' |
| 113 | latex_documents = [ |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 114 | ('c-api/index', 'c-api.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 115 | 'The Python/C API', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 116 | ('distutils/index', 'distutils.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 117 | 'Distributing Python Modules', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 118 | ('documenting/index', 'documenting.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 119 | 'Documenting Python', 'Georg Brandl', 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 120 | ('extending/index', 'extending.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 121 | 'Extending and Embedding Python', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 122 | ('install/index', 'install.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 123 | 'Installing Python Modules', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 124 | ('library/index', 'library.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 125 | 'The Python Library Reference', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 126 | ('reference/index', 'reference.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 127 | 'The Python Language Reference', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 128 | ('tutorial/index', 'tutorial.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 129 | 'Python Tutorial', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 130 | ('using/index', 'using.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 131 | 'Using Python', _stdauthor, 'manual'), |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 132 | ('whatsnew/' + version, 'whatsnew.tex', |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 133 | 'What\'s New in Python', 'A. M. Kuchling', 'howto'), |
| 134 | ] |
| 135 | # Collect all HOWTOs individually |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 136 | latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex', |
Benjamin Peterson | f608c61 | 2008-11-16 18:33:53 +0000 | [diff] [blame] | 137 | '', _stdauthor, 'howto') |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 138 | for fn in os.listdir('howto') |
| 139 | if fn.endswith('.rst') and fn != 'index.rst') |
| 140 | |
| 141 | # Additional stuff for the LaTeX preamble. |
| 142 | latex_preamble = r''' |
| 143 | \authoraddress{ |
| 144 | \strong{Python Software Foundation}\\ |
| 145 | Email: \email{docs@python.org} |
| 146 | } |
Benjamin Peterson | 6cadba7 | 2008-11-19 22:38:29 +0000 | [diff] [blame] | 147 | \let\Verbatim=\OriginalVerbatim |
| 148 | \let\endVerbatim=\endOriginalVerbatim |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 149 | ''' |
| 150 | |
| 151 | # Documents to append as an appendix to all manuals. |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 152 | latex_appendices = ['glossary', 'about', 'license', 'copyright'] |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 153 | |
Benjamin Peterson | a833206 | 2009-09-11 22:36:27 +0000 | [diff] [blame] | 154 | # Get LaTeX to handle Unicode correctly |
| 155 | latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}'} |
| 156 | |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 157 | # Options for the coverage checker |
| 158 | # -------------------------------- |
| 159 | |
| 160 | # The coverage checker will ignore all modules/functions/classes whose names |
| 161 | # match any of the following regexes (using re.match). |
| 162 | coverage_ignore_modules = [ |
| 163 | r'[T|t][k|K]', |
| 164 | r'Tix', |
| 165 | r'distutils.*', |
| 166 | ] |
| 167 | |
| 168 | coverage_ignore_functions = [ |
| 169 | 'test($|_)', |
| 170 | ] |
| 171 | |
| 172 | coverage_ignore_classes = [ |
| 173 | ] |
| 174 | |
| 175 | # Glob patterns for C source files for C API coverage, relative to this directory. |
| 176 | coverage_c_path = [ |
| 177 | '../Include/*.h', |
| 178 | ] |
| 179 | |
| 180 | # Regexes to find C items in the source files. |
| 181 | coverage_c_regexes = { |
| 182 | 'cfunction': (r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'), |
| 183 | 'data': (r'^PyAPI_DATA\(.*\)\s+([^_][\w_]+)'), |
| 184 | 'macro': (r'^#define ([^_][\w_]+)\(.*\)[\s|\\]'), |
| 185 | } |
| 186 | |
| 187 | # The coverage checker will ignore all C items whose names match these regexes |
| 188 | # (using re.match) -- the keys must be the same as in coverage_c_regexes. |
| 189 | coverage_ignore_c_items = { |
| 190 | # 'cfunction': [...] |
| 191 | } |