conf.py 5.6 KB
Newer Older
1 2 3
#
# Python documentation build configuration file
#
4 5
# This file is execfile()d with the current directory set to its containing dir.
#
6 7
# The contents of this file are pickled, so don't put values in the namespace
# 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

12 13
# General configuration
# ---------------------
14

15 16
extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
              'pyspecific', 'c_annotations']
17

18 19
# General substitutions.
project = 'Python'
20
copyright = '1990-%s, Python Software Foundation' % time.strftime('%Y')
21

22 23 24 25
# We look for the Include/patchlevel.h file in the current Python source tree
# and replace the values accordingly.
import patchlevel
version, release = patchlevel.get_version_info()
26 27 28 29 30 31 32

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
today = ''
# Else, today_fmt is used as the format for a strftime call.
today_fmt = '%B %d, %Y'

33 34 35
# By default, highlight as Python 3.
highlight_language = 'python3'

36
# Require Sphinx 1.2 for build.
37
needs_sphinx = '1.2'
38

39 40 41 42

# Options for HTML output
# -----------------------

43
# Use our custom theme.
44
html_theme = 'pydoctheme'
45
html_theme_path = ['tools']
46 47
html_theme_options = {'collapsiblesidebar': True}

48
# Short title used e.g. for <title> HTML tags.
49 50
html_short_title = '%s Documentation' % release

51 52
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
53
html_last_updated_fmt = '%b %d, %Y'
54

55
# Path to find HTML templates.
56
templates_path = ['tools/templates']
57

58 59
# Custom sidebar templates, filenames relative to this file.
html_sidebars = {
60
    'index': 'indexsidebar.html',
61 62 63 64
}

# Additional templates that should be rendered to pages.
html_additional_pages = {
65
    'download': 'download.html',
Christian Heimes's avatar
Christian Heimes committed
66
    'index': 'indexcontent.html',
67 68
}

69
# Output an OpenSearch description file.
70
html_use_opensearch = 'https://docs.python.org/' + version
71 72

# Additional static files.
73
html_static_path = ['tools/static']
74

75
# Output file base name for HTML help builder.
Christian Heimes's avatar
Christian Heimes committed
76
htmlhelp_basename = 'python' + release.replace('.', '')
77

78 79 80
# Split the index
html_split_index = True

81

82 83 84
# Options for LaTeX output
# ------------------------

85 86 87 88 89 90 91 92
# The paper size ('letter' or 'a4').
latex_paper_size = 'a4'

# The font size ('10pt', '11pt' or '12pt').
latex_font_size = '10pt'

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
93
_stdauthor = r'Guido van Rossum\\and the Python development team'
94
latex_documents = [
Christian Heimes's avatar
Christian Heimes committed
95
    ('c-api/index', 'c-api.tex',
96
     'The Python/C API', _stdauthor, 'manual'),
97
    ('distributing/index', 'distributing.tex',
98
     'Distributing Python Modules', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
99
    ('extending/index', 'extending.tex',
100
     'Extending and Embedding Python', _stdauthor, 'manual'),
101
    ('installing/index', 'installing.tex',
102
     'Installing Python Modules', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
103
    ('library/index', 'library.tex',
104
     'The Python Library Reference', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
105
    ('reference/index', 'reference.tex',
106
     'The Python Language Reference', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
107
    ('tutorial/index', 'tutorial.tex',
108
     'Python Tutorial', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
109
    ('using/index', 'using.tex',
Georg Brandl's avatar
Georg Brandl committed
110
     'Python Setup and Usage', _stdauthor, 'manual'),
111 112
    ('faq/index', 'faq.tex',
     'Python Frequently Asked Questions', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
113
    ('whatsnew/' + version, 'whatsnew.tex',
114 115 116
     'What\'s New in Python', 'A. M. Kuchling', 'howto'),
]
# Collect all HOWTOs individually
Christian Heimes's avatar
Christian Heimes committed
117
latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex',
118
                        '', _stdauthor, 'howto')
119 120 121 122 123 124 125 126 127
                       for fn in os.listdir('howto')
                       if fn.endswith('.rst') and fn != 'index.rst')

# Additional stuff for the LaTeX preamble.
latex_preamble = r'''
\authoraddress{
  \strong{Python Software Foundation}\\
  Email: \email{docs@python.org}
}
128 129
\let\Verbatim=\OriginalVerbatim
\let\endVerbatim=\endOriginalVerbatim
130
'''
131

132
# Documents to append as an appendix to all manuals.
Christian Heimes's avatar
Christian Heimes committed
133
latex_appendices = ['glossary', 'about', 'license', 'copyright']
134

Benjamin Peterson's avatar
Benjamin Peterson committed
135
# Get LaTeX to handle Unicode correctly
Georg Brandl's avatar
Georg Brandl committed
136
latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''}
Benjamin Peterson's avatar
Benjamin Peterson committed
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
# Options for the coverage checker
# --------------------------------

# The coverage checker will ignore all modules/functions/classes whose names
# match any of the following regexes (using re.match).
coverage_ignore_modules = [
    r'[T|t][k|K]',
    r'Tix',
    r'distutils.*',
]

coverage_ignore_functions = [
    'test($|_)',
]

coverage_ignore_classes = [
]

# Glob patterns for C source files for C API coverage, relative to this directory.
coverage_c_path = [
    '../Include/*.h',
]

# Regexes to find C items in the source files.
coverage_c_regexes = {
    'cfunction': (r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'),
    'data': (r'^PyAPI_DATA\(.*\)\s+([^_][\w_]+)'),
    'macro': (r'^#define ([^_][\w_]+)\(.*\)[\s|\\]'),
}

# The coverage checker will ignore all C items whose names match these regexes
# (using re.match) -- the keys must be the same as in coverage_c_regexes.
coverage_ignore_c_items = {
#    'cfunction': [...]
}
174

175 176 177 178 179 180 181 182 183 184

# Options for the link checker
# ----------------------------

# Ignore certain URLs.
linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+',
                    # Ignore PEPs for now, they all have permanent redirects.
                    r'http://www.python.org/dev/peps/pep-\d+']


185 186 187 188 189
# Options for extensions
# ----------------------

# Relative filename of the reference count data file.
refcount_file = 'data/refcounts.dat'