diff options
Diffstat (limited to 'doc/config.rst')
| -rw-r--r-- | doc/config.rst | 166 |
1 files changed, 102 insertions, 64 deletions
diff --git a/doc/config.rst b/doc/config.rst index 26079e69..1e66d090 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -45,7 +45,8 @@ Important points to note: * There is a special object named ``tags`` available in the config file. It can be used to query and change the tags (see :ref:`tags`). Use ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')`` - to change. + to change. Only tags set via the ``-t`` command-line option or via + ``tags.add('tag')`` can be queried using ``tags.has('tag')``. Note that the current builder tag is not available in ``conf.py``, as it is created *after* the builder is initialized. @@ -115,44 +116,16 @@ General configuration .. versionadded:: 1.0 -.. confval:: unused_docs - - A list of document names that are present, but not currently included in the - toctree. Use this setting to suppress the warning that is normally emitted - in that case. - - .. deprecated:: 1.0 - Use :confval:`exclude_patterns` instead. - -.. confval:: exclude_trees - - A list of directory paths, relative to the source directory, that are to be - recursively excluded from the search for source files, that is, their - subdirectories won't be searched too. The default is ``[]``. - - .. versionadded:: 0.4 - - .. deprecated:: 1.0 - Use :confval:`exclude_patterns` instead. - -.. confval:: exclude_dirnames - - A list of directory names that are to be excluded from any recursive - operation Sphinx performs (e.g. searching for source files or copying static - files). This is useful, for example, to exclude version-control-specific - directories like ``'CVS'``. The default is ``[]``. - - .. versionadded:: 0.5 - - .. deprecated:: 1.0 - Use :confval:`exclude_patterns` instead. - .. confval:: templates_path A list of paths that contain extra templates (or templates that overwrite builtin/theme-specific templates). Relative paths are taken as relative to the configuration directory. + .. versionchanged:: 1.3 + As these files are not meant to be built, they are automatically added to + :confval:`exclude_patterns`. + .. confval:: template_bridge A string with the fully-qualified name of a callable (or simply a class) that @@ -341,8 +314,8 @@ Project information If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at the ends of lines and ``<BLANKLINE>`` markers are removed for all code blocks showing interactive Python sessions (i.e. doctests). Default is - true. See the extension :mod:`~sphinx.ext.doctest` for more possibilities - of including doctests. + ``True``. See the extension :mod:`~sphinx.ext.doctest` for more + possibilities of including doctests. .. versionadded:: 1.0 .. versionchanged:: 1.1 @@ -354,7 +327,7 @@ Project information Options for internationalization -------------------------------- -These options influence Sphinx' *Native Language Support*. See the +These options influence Sphinx's *Native Language Support*. See the documentation on :ref:`intl` for details. .. confval:: language @@ -435,6 +408,32 @@ documentation on :ref:`intl` for details. By default, the document ``markup/code.rst`` ends up in the ``markup`` text domain. With this option set to ``False``, it is ``markup/code``. +.. confval:: gettext_uuid + + If true, Sphinx generates uuid information for version tracking in message + catalogs. + + The default is ``True``. + + .. versionadded:: 1.3 + +.. confval:: gettext_location + + If true, Sphinx generates location information for messages in message + catalogs. + + The default is ``True``. + + .. versionadded:: 1.3 + +.. confval:: gettext_auto_build + + If true, Sphinx builds mo file for each translation catalog files. + + The default is ``True``. + + .. versionadded:: 1.3 + .. _html-options: @@ -442,7 +441,7 @@ Options for HTML output ----------------------- These options influence HTML as well as HTML Help output, and other builders -that use Sphinx' HTMLWriter class. +that use Sphinx's HTMLWriter class. .. confval:: html_theme @@ -470,14 +469,14 @@ that use Sphinx' HTMLWriter class. .. confval:: html_style The style sheet to use for HTML pages. A file of that name must exist either - in Sphinx' :file:`static/` path, or in one of the custom paths given in + in Sphinx's :file:`static/` path, or in one of the custom paths given in :confval:`html_static_path`. Default is the stylesheet given by the selected theme. If you only want to add or override a few things compared to the theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet. .. confval:: html_title - The "title" for HTML documentation generated with Sphinx' own templates. + The "title" for HTML documentation generated with Sphinx's own templates. This is appended to the ``<title>`` tag of individual pages, and used in the navigation bar as the "topmost" element. It defaults to :samp:`'{<project>} v{<revision>} documentation'` (with the values coming from the config @@ -513,9 +512,10 @@ that use Sphinx' HTMLWriter class. .. confval:: html_favicon If given, this must be the name of an image file (path relative to the - :term:`configuration directory`) that is the favicon of the docs. Modern browsers use this - as icon for tabs, windows and bookmarks. It should be a Windows-style icon - file (``.ico``), which is 16x16 or 32x32 pixels large. Default: ``None``. + :term:`configuration directory`) that is the favicon of the docs. Modern + browsers use this as the icon for tabs, windows and bookmarks. It should + be a Windows-style icon file (``.ico``), which is 16x16 or 32x32 + pixels large. Default: ``None``. .. versionadded:: 0.4 The image file will be copied to the ``_static`` directory of the output @@ -557,8 +557,9 @@ that use Sphinx' HTMLWriter class. .. confval:: html_use_smartypants - If true, *SmartyPants* will be used to convert quotes and dashes to - typographically correct entities. Default: ``True``. + If true, `SmartyPants <http://daringfireball.net/projects/smartypants/>`_ + will be used to convert quotes and dashes to typographically correct + entities. Default: ``True``. .. confval:: html_add_permalinks @@ -600,7 +601,8 @@ that use Sphinx' HTMLWriter class. Builtin sidebar templates that can be rendered are: - * **localtoc.html** -- a fine-grained table of contents of the current document + * **localtoc.html** -- a fine-grained table of contents of the current + document * **globaltoc.html** -- a coarse-grained table of contents for the whole documentation set, collapsed * **relations.html** -- two links to the previous and next documents @@ -717,13 +719,16 @@ that use Sphinx' HTMLWriter class. .. confval:: html_translator_class A string with the fully-qualified name of a HTML Translator class, that is, a - subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used - to translate document trees to HTML. Default is ``None`` (use the builtin - translator). + subclass of Sphinx's :class:`~sphinx.writers.html.HTMLTranslator`, that is + used to translate document trees to HTML. Default is ``None`` (use the + builtin translator). + + .. seealso:: :meth:`~sphinx.application.Sphinx.set_translator` .. confval:: html_show_copyright - If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``. + If true, "(C) Copyright ..." is shown in the HTML footer. Default is + ``True``. .. versionadded:: 1.0 @@ -766,10 +771,37 @@ that use Sphinx' HTMLWriter class. Support is present for these languages: + * ``da`` -- Danish + * ``nl`` -- Dutch * ``en`` -- English + * ``fi`` -- Finnish + * ``fr`` -- French + * ``de`` -- German + * ``hu`` -- Hungarian + * ``it`` -- Italian * ``ja`` -- Japanese + * ``no`` -- Norwegian + * ``pr`` -- Portuguese + * ``ro`` -- Romanian + * ``ru`` -- Russian + * ``es`` -- Spanish + * ``sv`` -- Swedish + * ``tr`` -- Turkish + + .. admonition:: Accelerating build speed + + Each language (except Japanese) provides its own stemming algorithm. + Sphinx uses a Python implementation by default. You can use a C + implementation to accelerate building the index file. + + * `PorterStemmer <https://pypi.python.org/pypi/PorterStemmer>`_ (``en``) + * `PyStemmer <https://pypi.python.org/pypi/PyStemmer>`_ (all languages) .. versionadded:: 1.1 + With support for ``en`` and ``ja``. + + .. versionchanged:: 1.3 + Added additional languages. .. confval:: html_search_options @@ -791,7 +823,7 @@ that use Sphinx' HTMLWriter class. .. confval:: html_search_scorer - The name of a javascript file (relative to the configuration directory) that + The name of a JavaScript file (relative to the configuration directory) that implements a search results scorer. If empty, the default will be used. .. XXX describe interface for scorer here @@ -900,7 +932,7 @@ the `Dublin Core metadata <http://dublincore.org/>`_. the optional guide information. See the OPF documentation at `<http://idpf.org/epub>`_ for details. If possible, default entries for the *cover* and *toc* types are automatically inserted. However, - the types can be explicitely overwritten if the default entries are not + the types can be explicitly overwritten if the default entries are not appropriate. Example:: epub_guide = (('cover', 'cover.html', u'Cover Page'),) @@ -940,8 +972,8 @@ the `Dublin Core metadata <http://dublincore.org/>`_. .. confval:: epub_tocdup This flag determines if a toc entry is inserted again at the beginning of - it's nested toc listing. This allows easier navitation to the top of - a chapter, but can be confusing because it mixes entries of differnet + its nested toc listing. This allows easier navigation to the top of + a chapter, but can be confusing because it mixes entries of different depth in one list. The default value is ``True``. .. confval:: epub_tocscope @@ -1024,11 +1056,11 @@ These options influence LaTeX output. ``'John \and Sarah'``. * *documentclass*: Normally, one of ``'manual'`` or ``'howto'`` (provided by Sphinx). Other document classes can be given, but they must include the - "sphinx" package in order to define Sphinx' custom LaTeX commands. - "howto" documents will not get appendices. Also, howtos will have a simpler - title page. + "sphinx" package in order to define Sphinx's custom LaTeX commands. "howto" + documents will not get appendices. Also, howtos will have a simpler title + page. - * *toctree_only*: Must be ``True`` or ``False``. If ``True``, the *startdoc* + * *toctree_only*: Must be ``True`` or ``False``. If true, the *startdoc* document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output. @@ -1135,6 +1167,12 @@ These options influence LaTeX output. "Rejne". You can also set this to ``''`` to disable fncychap. ``'preamble'`` Additional preamble content, default empty. + ``'figure_align'`` + Latex figure float alignment, default 'htbp' (here, top, bottom, page). + Whenever an image doesn't fit into the current page, it will be + 'floated' into the next page but may be preceded by any other text. + If you don't like this behavior, use 'H' which will disable floating + and position figures strictly in the order they appear in the source. ``'footer'`` Additional footer content (before the indices), default empty. @@ -1167,7 +1205,8 @@ These options influence LaTeX output. ``'\\printindex'``. Override if you want to generate the index differently or append some content after the index. - * Keys that are set by other options and therefore should not be overridden are: + * Keys that are set by other options and therefore should not be overridden + are: ``'docclass'`` ``'classoptions'`` @@ -1324,7 +1363,7 @@ These options influence Texinfo output. file. * *category*: Specifies the section which this entry will appear in the top-level ``DIR`` menu file. - * *toctree_only*: Must be ``True`` or ``False``. If ``True``, the *startdoc* + * *toctree_only*: Must be ``True`` or ``False``. If true, the *startdoc* document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the Texinfo @@ -1400,7 +1439,6 @@ These options influence Texinfo output. ``'project'`` ``'release'`` ``'title'`` - ``'direntry'`` .. versionadded:: 1.1 @@ -1434,9 +1472,9 @@ Options for the linkcheck builder .. confval:: linkcheck_anchors - True or false, whether to check the validity of ``#anchor``\ s in links. - Since this requires downloading the whole document, it's considerably slower - when enabled. Default is ``True``. + If true, check the validity of ``#anchor``\ s in links. Since this requires + downloading the whole document, it's considerably slower when enabled. + Default is ``True``. .. versionadded:: 1.2 @@ -1446,7 +1484,7 @@ Options for the XML builder .. confval:: xml_pretty - If True, pretty-print the XML. Default is ``True``. + If true, pretty-print the XML. Default is ``True``. .. versionadded:: 1.2 |