1 # -*- coding: utf-8 -*- 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 8 # that aren't pickleable (module imports are okay, they're removed automatically). 9 10 import sys, os, time 11 sys.path.append(os.path.abspath('tools/extensions')) 12 13 # General configuration 14 # --------------------- 15 16 extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest', 17 'pyspecific', 'c_annotations'] 18 19 # General substitutions. 20 project = 'Python' 21 copyright = '1990-%s, Python Software Foundation' % time.strftime('%Y') 22 23 # We look for the Include/patchlevel.h file in the current Python source tree 24 # and replace the values accordingly. 25 import patchlevel 26 version, release = patchlevel.get_version_info() 27 28 # There are two options for replacing |today|: either, you set today to some 29 # non-false value, then it is used: 30 today = '' 31 # Else, today_fmt is used as the format for a strftime call. 32 today_fmt = '%B %d, %Y' 33 34 # List of files that shouldn't be included in the build. 35 exclude_patterns = [ 36 'maclib/scrap.rst', 37 'library/xmllib.rst', 38 'library/xml.etree.rst', 39 ] 40 41 # Require Sphinx 1.2 for build. 42 needs_sphinx = '1.2' 43 44 45 # Options for HTML output 46 # ----------------------- 47 48 html_theme = 'default' 49 html_theme_options = {'collapsiblesidebar': True} 50 51 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 52 # 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 # Custom sidebar templates, filenames relative to this file. 59 html_sidebars = { 60 'index': 'indexsidebar.html', 61 } 62 63 # Additional templates that should be rendered to pages. 64 html_additional_pages = { 65 'download': 'download.html', 66 'index': 'indexcontent.html', 67 } 68 69 # Output an OpenSearch description file. 70 html_use_opensearch = 'https://docs.python.org/' 71 72 # Additional static files. 73 html_static_path = ['tools/static'] 74 75 # Output file base name for HTML help builder. 76 htmlhelp_basename = 'python' + release.replace('.', '') 77 78 # Split the index 79 html_split_index = True 80 81 82 # Options for LaTeX output 83 # ------------------------ 84 85 # The paper size ('letter' or 'a4'). 86 latex_paper_size = 'a4' 87 88 # The font size ('10pt', '11pt' or '12pt'). 89 latex_font_size = '10pt' 90 91 # Grouping the document tree into LaTeX files. List of tuples 92 # (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 = [ 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'), 99 ('extending/index', 'extending.tex', 100 'Extending and Embedding Python', _stdauthor, 'manual'), 101 ('installing/index', 'installing.tex', 102 'Installing Python Modules', _stdauthor, 'manual'), 103 ('library/index', 'library.tex', 104 'The Python Library Reference', _stdauthor, 'manual'), 105 ('reference/index', 'reference.tex', 106 'The Python Language Reference', _stdauthor, 'manual'), 107 ('tutorial/index', 'tutorial.tex', 108 'Python Tutorial', _stdauthor, 'manual'), 109 ('using/index', 'using.tex', 110 'Python Setup and Usage', _stdauthor, 'manual'), 111 ('faq/index', 'faq.tex', 112 'Python Frequently Asked Questions', _stdauthor, 'manual'), 113 ('whatsnew/' + version, 'whatsnew.tex', 114 'What\'s New in Python', 'A. M. Kuchling', 'howto'), 115 ] 116 # Collect all HOWTOs individually 117 latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex', 118 '', _stdauthor, 'howto') 119 for fn in os.listdir('howto') 120 if fn.endswith('.rst') and fn != 'index.rst') 121 122 # Additional stuff for the LaTeX preamble. 123 latex_preamble = r''' 124 \authoraddress{ 125 \strong{Python Software Foundation}\\ 126 Email: \email{docs (at] python.org} 127 } 128 \let\Verbatim=\OriginalVerbatim 129 \let\endVerbatim=\endOriginalVerbatim 130 ''' 131 132 # Documents to append as an appendix to all manuals. 133 latex_appendices = ['glossary', 'about', 'license', 'copyright'] 134 135 # Get LaTeX to handle Unicode correctly 136 latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''} 137 138 139 # Options for Epub output 140 # ----------------------- 141 142 epub_author = 'Python Documentation Authors' 143 epub_publisher = 'Python Software Foundation' 144 145 146 # Options for the coverage checker 147 # -------------------------------- 148 149 # The coverage checker will ignore all modules/functions/classes whose names 150 # match any of the following regexes (using re.match). 151 coverage_ignore_modules = [ 152 r'[T|t][k|K]', 153 r'Tix', 154 r'distutils.*', 155 ] 156 157 coverage_ignore_functions = [ 158 'test($|_)', 159 ] 160 161 coverage_ignore_classes = [ 162 ] 163 164 # Glob patterns for C source files for C API coverage, relative to this directory. 165 coverage_c_path = [ 166 '../Include/*.h', 167 ] 168 169 # Regexes to find C items in the source files. 170 coverage_c_regexes = { 171 'cfunction': (r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'), 172 'data': (r'^PyAPI_DATA\(.*\)\s+([^_][\w_]+)'), 173 'macro': (r'^#define ([^_][\w_]+)\(.*\)[\s|\\]'), 174 } 175 176 # The coverage checker will ignore all C items whose names match these regexes 177 # (using re.match) -- the keys must be the same as in coverage_c_regexes. 178 coverage_ignore_c_items = { 179 # 'cfunction': [...] 180 } 181 182 183 # Options for the link checker 184 # ---------------------------- 185 186 # Ignore certain URLs. 187 linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+', 188 # Ignore PEPs for now, they all have permanent redirects. 189 r'http://www.python.org/dev/peps/pep-\d+'] 190 191 192 # Options for extensions 193 # ---------------------- 194 195 # Relative filename of the reference count data file. 196 refcount_file = 'data/refcounts.dat' 197
