| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame^] | 1 | .. highlightlang:: rest |
| 2 | |
| 3 | The Sphinx build system |
| 4 | ======================= |
| 5 | |
| 6 | .. XXX: intro... |
| 7 | |
| 8 | .. _doc-build-config: |
| 9 | |
| 10 | The build configuration file |
| 11 | ---------------------------- |
| 12 | |
| 13 | The documentation root, that is the ``Doc`` subdirectory of the source |
| 14 | distribution, contains a file named ``conf.py``. This file is called the "build |
| 15 | configuration file", and it contains several variables that are read and used |
| 16 | during a build run. |
| 17 | |
| 18 | These variables are: |
| 19 | |
| 20 | version : string |
| 21 | A string that is used as a replacement for the ``|version|`` reST |
| 22 | substitution. It should be the Python version the documentation refers to. |
| 23 | This consists only of the major and minor version parts, e.g. ``2.5``, even |
| 24 | for version 2.5.1. |
| 25 | |
| 26 | release : string |
| 27 | A string that is used as a replacement for the ``|release|`` reST |
| 28 | substitution. It should be the full version string including |
| 29 | alpha/beta/release candidate tags, e.g. ``2.5.2b3``. |
| 30 | |
| 31 | Both ``release`` and ``version`` can be ``'auto'``, which means that they are |
| 32 | determined at runtime from the ``Include/patchlevel.h`` file, if a complete |
| 33 | Python source distribution can be found, or else from the interpreter running |
| 34 | Sphinx. |
| 35 | |
| 36 | today_fmt : string |
| 37 | A ``strftime`` format that is used to format a replacement for the |
| 38 | ``|today|`` reST substitution. |
| 39 | |
| 40 | today : string |
| 41 | A string that can contain a date that should be written to the documentation |
| 42 | output literally. If this is nonzero, it is used instead of |
| 43 | ``strftime(today_fmt)``. |
| 44 | |
| 45 | unused_files : list of strings |
| 46 | A list of reST filenames that are to be disregarded during building. This |
| 47 | could be docs for temporarily disabled modules or documentation that's not |
| 48 | yet ready for public consumption. |
| 49 | |
| 50 | last_updated_format : string |
| 51 | If this is not an empty string, it will be given to ``time.strftime()`` and |
| 52 | written to each generated output file after "last updated on:". |
| 53 | |
| 54 | use_smartypants : bool |
| 55 | If true, use SmartyPants to convert quotes and dashes to the typographically |
| 56 | correct entities. |
| 57 | |
| 58 | add_function_parentheses : bool |
| 59 | If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and |
| 60 | ``:cfunc:`` cross-references. |