Doc/documenting/sphinx.rst

.. highlightlang:: rest

The Sphinx build system
=======================

.. XXX: intro...

.. _doc-build-config:

The build configuration file
----------------------------

The documentation root, that is the ``Doc`` subdirectory of the source
distribution, contains a file named ``conf.py``.  This file is called the "build
configuration file", and it contains several variables that are read and used
during a build run.

These variables are:

version : string
   A string that is used as a replacement for the ``|version|`` reST
   substitution.  It should be the Python version the documentation refers to.
   This consists only of the major and minor version parts, e.g. ``2.5``, even
   for version 2.5.1.

release : string
   A string that is used as a replacement for the ``|release|`` reST
   substitution.  It should be the full version string including
   alpha/beta/release candidate tags, e.g. ``2.5.2b3``.

Both ``release`` and ``version`` can be ``'auto'``, which means that they are
determined at runtime from the ``Include/patchlevel.h`` file, if a complete
Python source distribution can be found, or else from the interpreter running
Sphinx.

today_fmt : string
   A ``strftime`` format that is used to format a replacement for the
   ``|today|`` reST substitution.

today : string
   A string that can contain a date that should be written to the documentation
   output literally.  If this is nonzero, it is used instead of
   ``strftime(today_fmt)``.

unused_files : list of strings
   A list of reST filenames that are to be disregarded during building.  This
   could be docs for temporarily disabled modules or documentation that's not
   yet ready for public consumption.

add_function_parentheses : bool
   If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
   ``:cfunc:`` cross-references.

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

Builder-specific variables
^^^^^^^^^^^^^^^^^^^^^^^^^^

html_download_base_url : string
   The base URL for download links on the download page.

html_last_updated_fmt : string
   If this is not an empty string, it will be given to ``time.strftime()`` and
   written to each generated output file after "last updated on:".

html_use_smartypants : bool
   If true, use SmartyPants to convert quotes and dashes to the typographically
   correct entities.

latex_paper_size : "letter" or "a4"
   The paper size option for the LaTeX document class.

latex_font_size : "10pt", "11pt" or "12pt"
   The font size option for the LaTeX document class.