Home | History | Annotate | Download | only in Doc
      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