conf.py 5.5 KB
Newer Older
1 2 3 4
# -*- coding: utf-8 -*-
#
# Python documentation build configuration file
#
5 6
# This file is execfile()d with the current directory set to its containing dir.
#
7 8
# 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).
9

10
import sys, os, time
Christian Heimes's avatar
Christian Heimes committed
11
sys.path.append(os.path.abspath('tools/sphinxext'))
12

13 14
# General configuration
# ---------------------
15

Christian Heimes's avatar
Christian Heimes committed
16
extensions = ['sphinx.ext.refcounting', 'sphinx.ext.coverage',
17
              'sphinx.ext.doctest', 'pyspecific']
18
templates_path = ['tools/sphinxext']
19

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

24 25 26 27 28 29
# The default replacements for |version| and |release|.
#
# The short X.Y version.
# version = '2.6'
# The full version, including alpha/beta/rc tags.
# release = '2.6a0'
30 31 32 33 34

# 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()
35 36 37 38 39 40 41 42

# 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'

# List of files that shouldn't be included in the build.
Christian Heimes's avatar
Christian Heimes committed
43 44 45 46 47 48 49 50 51 52 53
unused_docs = [
    'whatsnew/2.0',
    'whatsnew/2.1',
    'whatsnew/2.2',
    'whatsnew/2.3',
    'whatsnew/2.4',
    'whatsnew/2.5',
    'whatsnew/2.6',
    'maclib/scrap',
    'library/xmllib',
    'library/xml.etree',
54 55
]

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

59 60 61 62 63 64 65 66 67 68 69
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = True


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

70 71
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
72
html_last_updated_fmt = '%b %d, %Y'
73 74 75

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
76
html_use_smartypants = True
77

78 79
# Custom sidebar templates, filenames relative to this file.
html_sidebars = {
80
    'index': 'indexsidebar.html',
81 82 83 84
}

# Additional templates that should be rendered to pages.
html_additional_pages = {
85
    'download': 'download.html',
Christian Heimes's avatar
Christian Heimes committed
86
    'index': 'indexcontent.html',
87 88
}

89 90 91 92 93 94
# Output an OpenSearch description file.
html_use_opensearch = 'http://docs.python.org/dev/3.0'

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

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

98

99 100 101
# Options for LaTeX output
# ------------------------

102 103 104 105 106 107 108 109 110 111
# 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]).
_stdauthor = r'Guido van Rossum\\Fred L. Drake, Jr., editor'
latex_documents = [
Christian Heimes's avatar
Christian Heimes committed
112
    ('c-api/index', 'c-api.tex',
113
     'The Python/C API', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
114
    ('distutils/index', 'distutils.tex',
115
     'Distributing Python Modules', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
116
    ('documenting/index', 'documenting.tex',
117
     'Documenting Python', 'Georg Brandl', 'manual'),
Christian Heimes's avatar
Christian Heimes committed
118
    ('extending/index', 'extending.tex',
119
     'Extending and Embedding Python', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
120
    ('install/index', 'install.tex',
121
     'Installing Python Modules', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
122
    ('library/index', 'library.tex',
123
     'The Python Library Reference', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
124
    ('reference/index', 'reference.tex',
125
     'The Python Language Reference', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
126
    ('tutorial/index', 'tutorial.tex',
127
     'Python Tutorial', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
128
    ('using/index', 'using.tex',
129
     'Using Python', _stdauthor, 'manual'),
Christian Heimes's avatar
Christian Heimes committed
130
    ('whatsnew/' + version, 'whatsnew.tex',
131 132 133
     'What\'s New in Python', 'A. M. Kuchling', 'howto'),
]
# Collect all HOWTOs individually
Christian Heimes's avatar
Christian Heimes committed
134
latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex',
135 136 137 138 139 140 141 142 143 144 145
                        'HOWTO', _stdauthor, 'howto')
                       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}
}
'''
146

147
# Documents to append as an appendix to all manuals.
Christian Heimes's avatar
Christian Heimes committed
148
latex_appendices = ['glossary', 'about', 'license', 'copyright']
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 174 175 176 177 178 179 180 181 182 183 184

# 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': [...]
}