| .. highlightlang:: python |
| |
| .. _build-config: |
| |
| The build configuration file |
| ============================ |
| |
| .. module:: conf |
| :synopsis: Build configuration file. |
| |
| The :term:`configuration directory` must contain a file named :file:`conf.py`. |
| This file (containing Python code) is called the "build configuration file" and |
| contains all configuration needed to customize Sphinx input and output behavior. |
| |
| The configuration file is executed as Python code at build time (using |
| :func:`execfile`, and with the current directory set to its containing |
| directory), and therefore can execute arbitrarily complex code. Sphinx then |
| reads simple names from the file's namespace as its configuration. |
| |
| Important points to note: |
| |
| * If not otherwise documented, values must be strings, and their default is the |
| empty string. |
| |
| * The term "fully-qualified name" refers to a string that names an importable |
| Python object inside a module; for example, the FQN |
| ``"sphinx.builders.Builder"`` means the ``Builder`` class in the |
| ``sphinx.builders`` module. |
| |
| * Remember that document names use ``/`` as the path separator and don't contain |
| the file name extension. |
| |
| * Since :file:`conf.py` is read as a Python file, the usual rules apply for |
| encodings and Unicode support: declare the encoding using an encoding cookie |
| (a comment like ``# -*- coding: utf-8 -*-``) and use Unicode string literals |
| when you include non-ASCII characters in configuration values. |
| |
| * The contents of the config namespace are pickled (so that Sphinx can find out |
| when configuration changes), so it may not contain unpickleable values -- |
| delete them from the namespace with ``del`` if appropriate. Modules are |
| removed automatically, so you don't need to ``del`` your imports after use. |
| |
| .. _conf-tags: |
| |
| * 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. 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. |
| |
| |
| General configuration |
| --------------------- |
| |
| .. confval:: extensions |
| |
| A list of strings that are module names of Sphinx extensions. These can be |
| extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones. |
| |
| Note that you can extend :data:`sys.path` within the conf file if your |
| extensions live in another directory -- but make sure you use absolute paths. |
| If your extension path is relative to the :term:`configuration directory`, |
| use :func:`os.path.abspath` like so:: |
| |
| import sys, os |
| |
| sys.path.append(os.path.abspath('sphinxext')) |
| |
| extensions = ['extname'] |
| |
| That way, you can load an extension called ``extname`` from the subdirectory |
| ``sphinxext``. |
| |
| The configuration file itself can be an extension; for that, you only need to |
| provide a :func:`setup` function in it. |
| |
| .. confval:: source_suffix |
| |
| The file name extension of source files. Only files with this suffix will be |
| read as sources. Default is ``'.rst'``. |
| |
| .. confval:: source_encoding |
| |
| The encoding of all reST source files. The recommended encoding, and the |
| default value, is ``'utf-8-sig'``. |
| |
| .. versionadded:: 0.5 |
| Previously, Sphinx accepted only UTF-8 encoded sources. |
| |
| .. confval:: master_doc |
| |
| The document name of the "master" document, that is, the document that |
| contains the root :rst:dir:`toctree` directive. Default is ``'contents'``. |
| |
| .. confval:: exclude_patterns |
| |
| A list of glob-style patterns that should be excluded when looking for source |
| files. [1]_ They are matched against the source file names relative to the |
| source directory, using slashes as directory separators on all platforms. |
| |
| Example patterns: |
| |
| - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file (replaces |
| entry in :confval:`unused_docs`) |
| - ``'library/xml'`` -- ignores the ``library/xml`` directory (replaces entry |
| in :confval:`exclude_trees`) |
| - ``'library/xml*'`` -- ignores all files and directories starting with |
| ``library/xml`` |
| - ``'**/.svn'`` -- ignores all ``.svn`` directories (replaces entry in |
| :confval:`exclude_dirnames`) |
| |
| :confval:`exclude_patterns` is also consulted when looking for static files |
| in :confval:`html_static_path`. |
| |
| .. versionadded:: 1.0 |
| |
| .. 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 |
| returns an instance of :class:`~sphinx.application.TemplateBridge`. This |
| instance is then used to render HTML documents, and possibly the output of |
| other builders (currently the changes builder). (Note that the template |
| bridge must be made theme-aware if HTML themes are to be used.) |
| |
| .. confval:: rst_epilog |
| |
| .. index:: pair: global; substitutions |
| |
| A string of reStructuredText that will be included at the end of every source |
| file that is read. This is the right place to add substitutions that should |
| be available in every file. An example:: |
| |
| rst_epilog = """ |
| .. |psf| replace:: Python Software Foundation |
| """ |
| |
| .. versionadded:: 0.6 |
| |
| .. confval:: rst_prolog |
| |
| A string of reStructuredText that will be included at the beginning of every |
| source file that is read. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: primary_domain |
| |
| .. index:: default; domain |
| primary; domain |
| |
| The name of the default :ref:`domain <domains>`. Can also be ``None`` to |
| disable a default domain. The default is ``'py'``. Those objects in other |
| domains (whether the domain name is given explicitly, or selected by a |
| :rst:dir:`default-domain` directive) will have the domain name explicitly |
| prepended when named (e.g., when the default domain is C, Python functions |
| will be named "Python function", not just "function"). |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: default_role |
| |
| .. index:: default; role |
| |
| The name of a reST role (builtin or Sphinx extension) to use as the default |
| role, that is, for text marked up ```like this```. This can be set to |
| ``'py:obj'`` to make ```filter``` a cross-reference to the Python function |
| "filter". The default is ``None``, which doesn't reassign the default role. |
| |
| The default role can always be set within individual documents using the |
| standard reST :rst:dir:`default-role` directive. |
| |
| .. versionadded:: 0.4 |
| |
| .. confval:: keep_warnings |
| |
| If true, keep warnings as "system message" paragraphs in the built documents. |
| Regardless of this setting, warnings are always written to the standard error |
| stream when ``sphinx-build`` is run. |
| |
| The default is ``False``, the pre-0.5 behavior was to always keep them. |
| |
| .. versionadded:: 0.5 |
| |
| .. confval:: needs_sphinx |
| |
| If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will |
| compare it with its version and refuse to build if it is too old. Default is |
| no requirement. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: needs_extensions |
| |
| This value can be a dictionary specifying version requirements for extensions |
| in :confval:`extensions`, e.g. ``needs_extensions = |
| {'sphinxcontrib.something': '1.5'}``. The version strings should be in the |
| form ``major.minor``. Requirements do not have to be specified for all |
| extensions, only for those you want to check. |
| |
| This requires that the extension specifies its version to Sphinx (see |
| :ref:`dev-extensions` for how to do that). |
| |
| .. versionadded:: 1.3 |
| |
| .. confval:: nitpicky |
| |
| If true, Sphinx will warn about *all* references where the target cannot be |
| found. Default is ``False``. You can activate this mode temporarily using |
| the :option:`-n` command-line switch. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: nitpick_ignore |
| |
| A list of ``(type, target)`` tuples (by default empty) that should be ignored |
| when generating warnings in "nitpicky mode". Note that ``type`` should |
| include the domain name if present. Example entries would be ``('py:func', |
| 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``. |
| |
| .. versionadded:: 1.1 |
| |
| |
| Project information |
| ------------------- |
| |
| .. confval:: project |
| |
| The documented project's name. |
| |
| .. confval:: copyright |
| |
| A copyright statement in the style ``'2008, Author Name'``. |
| |
| .. confval:: version |
| |
| The major project version, used as the replacement for ``|version|``. For |
| example, for the Python documentation, this may be something like ``2.6``. |
| |
| .. confval:: release |
| |
| The full project version, used as the replacement for ``|release|`` and |
| e.g. in the HTML templates. For example, for the Python documentation, this |
| may be something like ``2.6.0rc1``. |
| |
| If you don't need the separation provided between :confval:`version` and |
| :confval:`release`, just set them both to the same value. |
| |
| .. confval:: today |
| today_fmt |
| |
| These values determine how to format the current date, used as the |
| replacement for ``|today|``. |
| |
| * If you set :confval:`today` to a non-empty value, it is used. |
| * Otherwise, the current time is formatted using :func:`time.strftime` and |
| the format given in :confval:`today_fmt`. |
| |
| The default is no :confval:`today` and a :confval:`today_fmt` of ``'%B %d, |
| %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent |
| %format for the selected locale). |
| |
| .. confval:: highlight_language |
| |
| The default language to highlight source code in. The default is |
| ``'python'``. The value should be a valid Pygments lexer name, see |
| :ref:`code-examples` for more details. |
| |
| .. versionadded:: 0.5 |
| |
| .. confval:: pygments_style |
| |
| The style name to use for Pygments highlighting of source code. The default |
| style is selected by the theme for HTML output, and ``'sphinx'`` otherwise. |
| |
| .. versionchanged:: 0.3 |
| If the value is a fully-qualified name of a custom Pygments style class, |
| this is then used as custom style. |
| |
| .. confval:: add_function_parentheses |
| |
| A boolean that decides whether parentheses are appended to function and |
| method role text (e.g. the content of ``:func:`input```) to signify that the |
| name is callable. Default is ``True``. |
| |
| .. confval:: add_module_names |
| |
| A boolean that decides whether module names are prepended to all |
| :term:`object` names (for object types where a "module" of some kind is |
| defined), e.g. for :rst:dir:`py:function` directives. Default is ``True``. |
| |
| .. confval:: show_authors |
| |
| A boolean that decides whether :rst:dir:`codeauthor` and |
| :rst:dir:`sectionauthor` directives produce any output in the built files. |
| |
| .. confval:: modindex_common_prefix |
| |
| A list of prefixes that are ignored for sorting the Python module index |
| (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, |
| not ``F``). This can be handy if you document a project that consists of a |
| single package. Works only for the HTML builder currently. Default is |
| ``[]``. |
| |
| .. versionadded:: 0.6 |
| |
| .. confval:: trim_footnote_reference_space |
| |
| Trim spaces before footnote references that are necessary for the reST parser |
| to recognize the footnote, but do not look too nice in the output. |
| |
| .. versionadded:: 0.6 |
| |
| .. confval:: trim_doctest_flags |
| |
| 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. |
| |
| .. versionadded:: 1.0 |
| .. versionchanged:: 1.1 |
| Now also removes ``<BLANKLINE>``. |
| |
| |
| .. _intl-options: |
| |
| Options for internationalization |
| -------------------------------- |
| |
| These options influence Sphinx's *Native Language Support*. See the |
| documentation on :ref:`intl` for details. |
| |
| .. confval:: language |
| |
| The code for the language the docs are written in. Any text automatically |
| generated by Sphinx will be in that language. Also, Sphinx will try to |
| substitute individual paragraphs from your documents with the translation |
| sets obtained from :confval:`locale_dirs`. In the LaTeX builder, a suitable |
| language will be selected as an option for the *Babel* package. Default is |
| ``None``, which means that no translation will be done. |
| |
| .. versionadded:: 0.5 |
| |
| Currently supported languages by Sphinx are: |
| |
| * ``bn`` -- Bengali |
| * ``ca`` -- Catalan |
| * ``cs`` -- Czech |
| * ``da`` -- Danish |
| * ``de`` -- German |
| * ``en`` -- English |
| * ``es`` -- Spanish |
| * ``et`` -- Estonian |
| * ``eu`` -- Basque |
| * ``fa`` -- Iranian |
| * ``fi`` -- Finnish |
| * ``fr`` -- French |
| * ``he`` -- Hebrew |
| * ``hr`` -- Croatian |
| * ``hu`` -- Hungarian |
| * ``id`` -- Indonesian |
| * ``it`` -- Italian |
| * ``ja`` -- Japanese |
| * ``ko`` -- Korean |
| * ``lt`` -- Lithuanian |
| * ``lv`` -- Latvian |
| * ``mk`` -- Macedonian |
| * ``nb_NO`` -- Norwegian Bokmal |
| * ``ne`` -- Nepali |
| * ``nl`` -- Dutch |
| * ``pl`` -- Polish |
| * ``pt_BR`` -- Brazilian Portuguese |
| * ``pt_PT`` -- European Portuguese |
| * ``ru`` -- Russian |
| * ``si`` -- Sinhala |
| * ``sk`` -- Slovak |
| * ``sl`` -- Slovenian |
| * ``sv`` -- Swedish |
| * ``tr`` -- Turkish |
| * ``uk_UA`` -- Ukrainian |
| * ``vi`` -- Vietnamese |
| * ``zh_CN`` -- Simplified Chinese |
| * ``zh_TW`` -- Traditional Chinese |
| |
| .. confval:: locale_dirs |
| |
| .. versionadded:: 0.5 |
| |
| Directories in which to search for additional message catalogs (see |
| :confval:`language`), relative to the source directory. The directories on |
| this path are searched by the standard :mod:`gettext` module. |
| |
| Internal messages are fetched from a text domain of ``sphinx``; so if you |
| add the directory :file:`./locale` to this settting, the message catalogs |
| (compiled from ``.po`` format using :program:`msgfmt`) must be in |
| :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`. The text domain of |
| individual documents depends on :confval:`gettext_compact`. |
| |
| The default is ``[]``. |
| |
| .. confval:: gettext_compact |
| |
| .. versionadded:: 1.1 |
| |
| If true, a document's text domain is its docname if it is a top-level |
| project file and its very base directory otherwise. |
| |
| 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: |
| |
| Options for HTML output |
| ----------------------- |
| |
| These options influence HTML as well as HTML Help output, and other builders |
| that use Sphinx's HTMLWriter class. |
| |
| .. confval:: html_theme |
| |
| The "theme" that the HTML output should use. See the :doc:`section about |
| theming <theming>`. The default is ``'default'``. |
| |
| .. versionadded:: 0.6 |
| |
| .. confval:: html_theme_options |
| |
| A dictionary of options that influence the look and feel of the selected |
| theme. These are theme-specific. For the options understood by the builtin |
| themes, see :ref:`this section <builtin-themes>`. |
| |
| .. versionadded:: 0.6 |
| |
| .. confval:: html_theme_path |
| |
| A list of paths that contain custom themes, either as subdirectories or as |
| zip files. Relative paths are taken as relative to the configuration |
| directory. |
| |
| .. versionadded:: 0.6 |
| |
| .. confval:: html_style |
| |
| The style sheet to use for HTML pages. A file of that name must exist either |
| 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'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 |
| values). |
| |
| .. confval:: html_short_title |
| |
| A shorter "title" for the HTML docs. This is used in for links in the header |
| and in the HTML Help docs. If not given, it defaults to the value of |
| :confval:`html_title`. |
| |
| .. versionadded:: 0.4 |
| |
| .. confval:: html_context |
| |
| A dictionary of values to pass into the template engine's context for all |
| pages. Single values can also be put in this dictionary using the |
| :option:`-A` command-line option of ``sphinx-build``. |
| |
| .. versionadded:: 0.5 |
| |
| .. confval:: html_logo |
| |
| If given, this must be the name of an image file (path relative to the |
| :term:`configuration directory`) that is the logo of the docs. It is placed |
| at the top of the sidebar; its width should therefore not exceed 200 pixels. |
| Default: ``None``. |
| |
| .. versionadded:: 0.4.1 |
| The image file will be copied to the ``_static`` directory of the output |
| HTML, but only if the file does not already exist there. |
| |
| .. 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 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 |
| HTML, but only if the file does not already exist there. |
| |
| .. confval:: html_static_path |
| |
| A list of paths that contain custom static files (such as style |
| sheets or script files). Relative paths are taken as relative to |
| the configuration directory. They are copied to the output's |
| :file:`_static` directory after the theme's static files, so a file |
| named :file:`default.css` will overwrite the theme's |
| :file:`default.css`. |
| |
| .. versionchanged:: 0.4 |
| The paths in :confval:`html_static_path` can now contain subdirectories. |
| |
| .. versionchanged:: 1.0 |
| The entries in :confval:`html_static_path` can now be single files. |
| |
| .. confval:: html_extra_path |
| |
| A list of paths that contain extra files not directly related to |
| the documentation, such as :file:`robots.txt` or :file:`.htaccess`. |
| Relative paths are taken as relative to the configuration |
| directory. They are copied to the output directory. They will |
| overwrite any existing file of the same name. |
| |
| As these files are not meant to be built, they are automatically added to |
| :confval:`exclude_patterns`. |
| |
| .. versionadded:: 1.2 |
| |
| .. confval:: html_last_updated_fmt |
| |
| If this is not the empty string, a 'Last updated on:' timestamp is inserted |
| at every page bottom, using the given :func:`strftime` format. Default is |
| ``'%b %d, %Y'`` (or a locale-dependent equivalent). |
| |
| .. confval:: html_use_smartypants |
| |
| 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 |
| |
| Sphinx will add "permalinks" for each heading and description environment as |
| paragraph signs that become visible when the mouse hovers over them. |
| |
| This value determines the text for the permalink; it defaults to ``"¶"``. |
| Set it to ``None`` or the empty string to disable permalinks. |
| |
| .. versionadded:: 0.6 |
| Previously, this was always activated. |
| |
| .. versionchanged:: 1.1 |
| This can now be a string to select the actual text of the link. |
| Previously, only boolean values were accepted. |
| |
| .. confval:: html_sidebars |
| |
| Custom sidebar templates, must be a dictionary that maps document names to |
| template names. |
| |
| The keys can contain glob-style patterns [1]_, in which case all matching |
| documents will get the specified sidebars. (A warning is emitted when a |
| more than one glob-style pattern matches for any document.) |
| |
| The values can be either lists or single strings. |
| |
| * If a value is a list, it specifies the complete list of sidebar templates |
| to include. If all or some of the default sidebars are to be included, |
| they must be put into this list as well. |
| |
| The default sidebars (for documents that don't match any pattern) are: |
| ``['localtoc.html', 'relations.html', 'sourcelink.html', |
| 'searchbox.html']``. |
| |
| * If a value is a single string, it specifies a custom sidebar to be added |
| between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries. This |
| is for compatibility with Sphinx versions before 1.0. |
| |
| Builtin sidebar templates that can be rendered are: |
| |
| * **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 |
| * **sourcelink.html** -- a link to the source of the current document, if |
| enabled in :confval:`html_show_sourcelink` |
| * **searchbox.html** -- the "quick search" box |
| |
| Example:: |
| |
| html_sidebars = { |
| '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'], |
| 'using/windows': ['windowssidebar.html', 'searchbox.html'], |
| } |
| |
| This will render the custom template ``windowssidebar.html`` and the quick |
| search box within the sidebar of the given document, and render the default |
| sidebars for all other pages (except that the local TOC is replaced by the |
| global TOC). |
| |
| .. versionadded:: 1.0 |
| The ability to use globbing keys and to specify multiple sidebars. |
| |
| Note that this value only has no effect if the chosen theme does not possess |
| a sidebar, like the builtin **scrolls** and **haiku** themes. |
| |
| .. confval:: html_additional_pages |
| |
| Additional templates that should be rendered to HTML pages, must be a |
| dictionary that maps document names to template names. |
| |
| Example:: |
| |
| html_additional_pages = { |
| 'download': 'customdownload.html', |
| } |
| |
| This will render the template ``customdownload.html`` as the page |
| ``download.html``. |
| |
| .. confval:: html_domain_indices |
| |
| If true, generate domain-specific indices in addition to the general index. |
| For e.g. the Python domain, this is the global module index. Default is |
| ``True``. |
| |
| This value can be a bool or a list of index names that should be generated. |
| To find out the index name for a specific index, look at the HTML file name. |
| For example, the Python module index has the name ``'py-modindex'``. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: html_use_modindex |
| |
| If true, add a module index to the HTML documents. Default is ``True``. |
| |
| .. deprecated:: 1.0 |
| Use :confval:`html_domain_indices`. |
| |
| .. confval:: html_use_index |
| |
| If true, add an index to the HTML documents. Default is ``True``. |
| |
| .. versionadded:: 0.4 |
| |
| .. confval:: html_split_index |
| |
| If true, the index is generated twice: once as a single page with all the |
| entries, and once as one page per starting letter. Default is ``False``. |
| |
| .. versionadded:: 0.4 |
| |
| .. confval:: html_copy_source |
| |
| If true, the reST sources are included in the HTML build as |
| :file:`_sources/{name}`. The default is ``True``. |
| |
| .. warning:: |
| |
| If this config value is set to ``False``, the JavaScript search function |
| will only display the titles of matching documents, and no excerpt from |
| the matching contents. |
| |
| .. confval:: html_show_sourcelink |
| |
| If true (and :confval:`html_copy_source` is true as well), links to the |
| reST sources will be added to the sidebar. The default is ``True``. |
| |
| .. versionadded:: 0.6 |
| |
| .. confval:: html_use_opensearch |
| |
| If nonempty, an `OpenSearch <http://opensearch.org>` description file will be |
| output, and all pages will contain a ``<link>`` tag referring to it. Since |
| OpenSearch doesn't support relative URLs for its search page location, the |
| value of this option must be the base URL from which these documents are |
| served (without trailing slash), e.g. ``"http://docs.python.org"``. The |
| default is ``''``. |
| |
| .. confval:: html_file_suffix |
| |
| This is the file name suffix for generated HTML files. The default is |
| ``".html"``. |
| |
| .. versionadded:: 0.4 |
| |
| .. confval:: html_link_suffix |
| |
| Suffix for generated links to HTML files. The default is whatever |
| :confval:`html_file_suffix` is set to; it can be set differently (e.g. to |
| support different web server setups). |
| |
| .. versionadded:: 0.6 |
| |
| .. confval:: html_translator_class |
| |
| A string with the fully-qualified name of a HTML Translator class, that is, a |
| 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``. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: html_show_sphinx |
| |
| If true, "Created using Sphinx" is shown in the HTML footer. Default is |
| ``True``. |
| |
| .. versionadded:: 0.4 |
| |
| .. confval:: html_output_encoding |
| |
| Encoding of HTML output files. Default is ``'utf-8'``. Note that this |
| encoding name must both be a valid Python encoding name and a valid HTML |
| ``charset`` value. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: html_compact_lists |
| |
| If true, list items containing only a single paragraph will not be rendered |
| with a ``<p>`` element. This is standard docutils behavior. Default: |
| ``True``. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: html_secnumber_suffix |
| |
| Suffix for section numbers. Default: ``". "``. Set to ``" "`` to suppress |
| the final dot on section numbers. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: html_search_language |
| |
| Language to be used for generating the HTML full-text search index. This |
| defaults to the global language selected with :confval:`language`. If there |
| is no support for this language, ``"en"`` is used which selects the English |
| language. |
| |
| 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 |
| |
| A dictionary with options for the search language support, empty by default. |
| The meaning of these options depends on the language selected. |
| |
| The English support has no options. |
| |
| The Japanese support has these options: |
| |
| * ``type`` -- ``'mecab'`` or ``'default'`` (selects either MeCab or |
| TinySegmenter word splitter algorithm) |
| * ``dic_enc`` -- the encoding for the MeCab algorithm |
| * ``dict`` -- the dictionary to use for the MeCab algorithm |
| * ``lib`` -- the library name for finding the MeCab library via ctypes if the |
| Python binding is not installed |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: html_search_scorer |
| |
| 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 |
| |
| .. versionadded:: 1.2 |
| |
| .. confval:: htmlhelp_basename |
| |
| Output file base name for HTML help builder. Default is ``'pydoc'``. |
| |
| |
| .. _epub-options: |
| |
| Options for epub output |
| ----------------------- |
| |
| These options influence the epub output. As this builder derives from the HTML |
| builder, the HTML options also apply where appropriate. The actual values for |
| some of the options is not really important, they just have to be entered into |
| the `Dublin Core metadata <http://dublincore.org/>`_. |
| |
| .. confval:: epub_basename |
| |
| The basename for the epub file. It defaults to the :confval:`project` name. |
| |
| .. confval:: epub_theme |
| |
| The HTML theme for the epub output. Since the default themes are not |
| optimized for small screen space, using the same theme for HTML and epub |
| output is usually not wise. This defaults to ``'epub'``, a theme designed to |
| save visual space. |
| |
| .. confval:: epub_theme_options |
| |
| A dictionary of options that influence the look and feel of the selected |
| theme. These are theme-specific. For the options understood by the builtin |
| themes, see :ref:`this section <builtin-themes>`. |
| |
| .. versionadded:: 1.2 |
| |
| .. confval:: epub_title |
| |
| The title of the document. It defaults to the :confval:`html_title` option |
| but can be set independently for epub creation. |
| |
| .. confval:: epub_author |
| |
| The author of the document. This is put in the Dublin Core metadata. The |
| default value is ``'unknown'``. |
| |
| .. confval:: epub_language |
| |
| The language of the document. This is put in the Dublin Core metadata. The |
| default is the :confval:`language` option or ``'en'`` if unset. |
| |
| .. confval:: epub_publisher |
| |
| The publisher of the document. This is put in the Dublin Core metadata. You |
| may use any sensible string, e.g. the project homepage. The default value is |
| ``'unknown'``. |
| |
| .. confval:: epub_copyright |
| |
| The copyright of the document. It defaults to the :confval:`copyright` |
| option but can be set independently for epub creation. |
| |
| .. confval:: epub_identifier |
| |
| An identifier for the document. This is put in the Dublin Core metadata. |
| For published documents this is the ISBN number, but you can also use an |
| alternative scheme, e.g. the project homepage. The default value is |
| ``'unknown'``. |
| |
| .. confval:: epub_scheme |
| |
| The publication scheme for the :confval:`epub_identifier`. This is put in |
| the Dublin Core metadata. For published books the scheme is ``'ISBN'``. If |
| you use the project homepage, ``'URL'`` seems reasonable. The default value |
| is ``'unknown'``. |
| |
| .. confval:: epub_uid |
| |
| A unique identifier for the document. This is put in the Dublin Core |
| metadata. You may use a random string. The default value is ``'unknown'``. |
| |
| .. confval:: epub_cover |
| |
| The cover page information. This is a tuple containing the filenames of |
| the cover image and the html template. The rendered html cover page is |
| inserted as the first item in the spine in :file:`content.opf`. If the |
| template filename is empty, no html cover page is created. No cover at all |
| is created if the tuple is empty. Examples:: |
| |
| epub_cover = ('_static/cover.png', 'epub-cover.html') |
| epub_cover = ('_static/cover.png', '') |
| epub_cover = () |
| |
| The default value is ``()``. |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: epub_guide |
| |
| Meta data for the guide element of :file:`content.opf`. This is a |
| sequence of tuples containing the *type*, the *uri* and the *title* of |
| 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 explicitly overwritten if the default entries are not |
| appropriate. Example:: |
| |
| epub_guide = (('cover', 'cover.html', u'Cover Page'),) |
| |
| The default value is ``()``. |
| |
| .. confval:: epub_pre_files |
| |
| Additional files that should be inserted before the text generated by |
| Sphinx. It is a list of tuples containing the file name and the title. |
| If the title is empty, no entry is added to :file:`toc.ncx`. Example:: |
| |
| epub_pre_files = [ |
| ('index.html', 'Welcome'), |
| ] |
| |
| The default value is ``[]``. |
| |
| .. confval:: epub_post_files |
| |
| Additional files that should be inserted after the text generated by Sphinx. |
| It is a list of tuples containing the file name and the title. This option |
| can be used to add an appendix. If the title is empty, no entry is added |
| to :file:`toc.ncx`. The default value is ``[]``. |
| |
| .. confval:: epub_exclude_files |
| |
| A list of files that are generated/copied in the build directory but should |
| not be included in the epub file. The default value is ``[]``. |
| |
| .. confval:: epub_tocdepth |
| |
| The depth of the table of contents in the file :file:`toc.ncx`. It should |
| be an integer greater than zero. The default value is 3. Note: A deeply |
| nested table of contents may be difficult to navigate. |
| |
| .. confval:: epub_tocdup |
| |
| This flag determines if a toc entry is inserted again at the beginning of |
| 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 |
| |
| This setting control the scope of the epub table of contents. The setting |
| can have the following values: |
| |
| * ``'default'`` -- include all toc entries that are not hidden (default) |
| * ``'includehidden'`` -- include all toc entries |
| |
| .. versionadded:: 1.2 |
| |
| .. confval:: epub_fix_images |
| |
| This flag determines if sphinx should try to fix image formats that are not |
| supported by some epub readers. At the moment palette images with a small |
| color table are upgraded. You need the Python Image Library (PIL) installed |
| to use this option. The default value is ``False`` because the automatic |
| conversion may lose information. |
| |
| .. versionadded:: 1.2 |
| |
| .. confval:: epub_max_image_width |
| |
| This option specifies the maximum width of images. If it is set to a value |
| greater than zero, images with a width larger than the given value are |
| scaled accordingly. If it is zero, no scaling is performed. The default |
| value is ``0``. You need the Python Image Library (PIL) installed to use |
| this option. |
| |
| .. versionadded:: 1.2 |
| |
| .. confval:: epub_show_urls |
| |
| Control whether to display URL addresses. This is very useful for |
| readers that have no other means to display the linked URL. The |
| settings can have the following values: |
| |
| * ``'inline'`` -- display URLs inline in parentheses (default) |
| * ``'footnote'`` -- display URLs in footnotes |
| * ``'no'`` -- do not display URLs |
| |
| The display of inline URLs can be customized by adding CSS rules for the |
| class ``link-target``. |
| |
| .. versionadded:: 1.2 |
| |
| .. confval:: epub_use_index |
| |
| If true, add an index to the epub document. It defaults to the |
| :confval:`html_use_index` option but can be set independently for epub |
| creation. |
| |
| .. versionadded:: 1.2 |
| |
| .. _latex-options: |
| |
| Options for LaTeX output |
| ------------------------ |
| |
| These options influence LaTeX output. |
| |
| .. confval:: latex_documents |
| |
| This value determines how to group the document tree into LaTeX source files. |
| It must be a list of tuples ``(startdocname, targetname, title, author, |
| documentclass, toctree_only)``, where the items are: |
| |
| * *startdocname*: document name that is the "root" of the LaTeX file. All |
| documents referenced by it in TOC trees will be included in the LaTeX file |
| too. (If you want only one LaTeX file, use your :confval:`master_doc` |
| here.) |
| * *targetname*: file name of the LaTeX file in the output directory. |
| * *title*: LaTeX document title. Can be empty to use the title of the |
| *startdoc*. This is inserted as LaTeX markup, so special characters like a |
| backslash or ampersand must be represented by the proper LaTeX commands if |
| they are to be inserted literally. |
| * *author*: Author for the LaTeX document. The same LaTeX markup caveat as |
| for *title* applies. Use ``\and`` to separate multiple authors, as in: |
| ``'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'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* |
| 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. |
| |
| .. versionadded:: 1.2 |
| In the past including your own document class required you to prepend the |
| document class name with the string "sphinx". This is not necessary |
| anymore. |
| |
| .. versionadded:: 0.3 |
| The 6th item ``toctree_only``. Tuples with 5 items are still accepted. |
| |
| .. confval:: latex_logo |
| |
| If given, this must be the name of an image file (relative to the |
| configuration directory) that is the logo of the docs. It is placed at the |
| top of the title page. Default: ``None``. |
| |
| .. confval:: latex_use_parts |
| |
| If true, the topmost sectioning unit is parts, else it is chapters. Default: |
| ``False``. |
| |
| .. versionadded:: 0.3 |
| |
| .. confval:: latex_appendices |
| |
| A list of document names to append as an appendix to all manuals. |
| |
| .. confval:: latex_domain_indices |
| |
| If true, generate domain-specific indices in addition to the general index. |
| For e.g. the Python domain, this is the global module index. Default is |
| ``True``. |
| |
| This value can be a bool or a list of index names that should be generated, |
| like for :confval:`html_domain_indices`. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: latex_use_modindex |
| |
| If true, add a module index to LaTeX documents. Default is ``True``. |
| |
| .. deprecated:: 1.0 |
| Use :confval:`latex_domain_indices`. |
| |
| .. confval:: latex_show_pagerefs |
| |
| If true, add page references after internal references. This is very useful |
| for printed copies of the manual. Default is ``False``. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: latex_show_urls |
| |
| Control whether to display URL addresses. This is very useful for printed |
| copies of the manual. The setting can have the following values: |
| |
| * ``'no'`` -- do not display URLs (default) |
| * ``'footnote'`` -- display URLs in footnotes |
| * ``'inline'`` -- display URLs inline in parentheses |
| |
| .. versionadded:: 1.0 |
| .. versionchanged:: 1.1 |
| This value is now a string; previously it was a boolean value, and a true |
| value selected the ``'inline'`` display. For backwards compatibility, |
| ``True`` is still accepted. |
| |
| .. confval:: latex_elements |
| |
| .. versionadded:: 0.5 |
| |
| A dictionary that contains LaTeX snippets that override those Sphinx usually |
| puts into the generated ``.tex`` files. |
| |
| Keep in mind that backslashes must be doubled in Python string literals to |
| avoid interpretation as escape sequences. |
| |
| * Keys that you may want to override include: |
| |
| ``'papersize'`` |
| Paper size option of the document class (``'a4paper'`` or |
| ``'letterpaper'``), default ``'letterpaper'``. |
| ``'pointsize'`` |
| Point size option of the document class (``'10pt'``, ``'11pt'`` or |
| ``'12pt'``), default ``'10pt'``. |
| ``'babel'`` |
| "babel" package inclusion, default ``'\\usepackage{babel}'``. |
| ``'fontpkg'`` |
| Font package inclusion, default ``'\\usepackage{times}'`` (which uses |
| Times and Helvetica). You can set this to ``''`` to use the Computer |
| Modern fonts. |
| |
| .. versionchanged:: 1.2 |
| Defaults to ``''`` when the :confval:`language` uses the Cyrillic |
| script. |
| ``'fncychap'`` |
| Inclusion of the "fncychap" package (which makes fancy chapter titles), |
| default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation, |
| ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because |
| the "Bjarne" style uses numbers spelled out in English). Other |
| "fncychap" styles you can try include "Lenny", "Glenn", "Conny" and |
| "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. |
| |
| * Keys that don't need be overridden unless in special cases are: |
| |
| ``'inputenc'`` |
| "inputenc" package inclusion, default |
| ``'\\usepackage[utf8]{inputenc}'``. |
| ``'cmappkg'`` |
| "cmap" package inclusion, default ``'\\usepackage{cmap}'``. |
| |
| .. versionadded:: 1.2 |
| ``'fontenc'`` |
| "fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``. |
| ``'maketitle'`` |
| "maketitle" call, default ``'\\maketitle'``. Override if you want to |
| generate a differently-styled title page. |
| ``'tableofcontents'`` |
| "tableofcontents" call, default ``'\\tableofcontents'``. Override if |
| you want to generate a different table of contents or put content |
| between the title page and the TOC. |
| ``'transition'`` |
| Commands used to display transitions, default |
| ``'\n\n\\bigskip\\hrule{}\\bigskip\n\n'``. Override if you want to |
| display transitions differently. |
| |
| .. versionadded:: 1.2 |
| ``'printindex'`` |
| "printindex" call, the last thing in the file, default |
| ``'\\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: |
| |
| ``'docclass'`` |
| ``'classoptions'`` |
| ``'title'`` |
| ``'date'`` |
| ``'release'`` |
| ``'author'`` |
| ``'logo'`` |
| ``'releasename'`` |
| ``'makeindex'`` |
| ``'shorthandoff'`` |
| |
| .. confval:: latex_docclass |
| |
| A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document |
| classes that will be used as the base for the two Sphinx classes. Default |
| is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: latex_additional_files |
| |
| A list of file names, relative to the configuration directory, to copy to the |
| build directory when building LaTeX output. This is useful to copy files |
| that Sphinx doesn't copy automatically, e.g. if they are referenced in custom |
| LaTeX added in ``latex_elements``. Image files that are referenced in source |
| files (e.g. via ``.. image::``) are copied automatically. |
| |
| You have to make sure yourself that the filenames don't collide with those of |
| any automatically copied files. |
| |
| .. versionadded:: 0.6 |
| |
| .. versionchanged:: 1.2 |
| This overrides the files which is provided from Sphinx such as sphinx.sty. |
| |
| .. confval:: latex_preamble |
| |
| Additional LaTeX markup for the preamble. |
| |
| .. deprecated:: 0.5 |
| Use the ``'preamble'`` key in the :confval:`latex_elements` value. |
| |
| .. confval:: latex_paper_size |
| |
| The output paper size (``'letter'`` or ``'a4'``). Default is ``'letter'``. |
| |
| .. deprecated:: 0.5 |
| Use the ``'papersize'`` key in the :confval:`latex_elements` value. |
| |
| .. confval:: latex_font_size |
| |
| The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``. |
| |
| .. deprecated:: 0.5 |
| Use the ``'pointsize'`` key in the :confval:`latex_elements` value. |
| |
| |
| .. _text-options: |
| |
| Options for text output |
| ----------------------- |
| |
| These options influence text output. |
| |
| .. confval:: text_newlines |
| |
| Determines which end-of-line character(s) are used in text output. |
| |
| * ``'unix'``: use Unix-style line endings (``\n``) |
| * ``'windows'``: use Windows-style line endings (``\r\n``) |
| * ``'native'``: use the line ending style of the platform the documentation |
| is built on |
| |
| Default: ``'unix'``. |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: text_sectionchars |
| |
| A string of 7 characters that should be used for underlining sections. |
| The first character is used for first-level headings, the second for |
| second-level headings and so on. |
| |
| The default is ``'*=-~"+`'``. |
| |
| .. versionadded:: 1.1 |
| |
| |
| .. _man-options: |
| |
| Options for manual page output |
| ------------------------------ |
| |
| These options influence manual page output. |
| |
| .. confval:: man_pages |
| |
| This value determines how to group the document tree into manual pages. It |
| must be a list of tuples ``(startdocname, name, description, authors, |
| section)``, where the items are: |
| |
| * *startdocname*: document name that is the "root" of the manual page. All |
| documents referenced by it in TOC trees will be included in the manual file |
| too. (If you want one master manual page, use your :confval:`master_doc` |
| here.) |
| * *name*: name of the manual page. This should be a short string without |
| spaces or special characters. It is used to determine the file name as |
| well as the name of the manual page (in the NAME section). |
| * *description*: description of the manual page. This is used in the NAME |
| section. |
| * *authors*: A list of strings with authors, or a single string. Can be an |
| empty string or list if you do not want to automatically generate an |
| AUTHORS section in the manual page. |
| * *section*: The manual page section. Used for the output file name as well |
| as in the manual page header. |
| |
| .. versionadded:: 1.0 |
| |
| .. confval:: man_show_urls |
| |
| If true, add URL addresses after links. Default is ``False``. |
| |
| .. versionadded:: 1.1 |
| |
| |
| .. _texinfo-options: |
| |
| Options for Texinfo output |
| -------------------------- |
| |
| These options influence Texinfo output. |
| |
| .. confval:: texinfo_documents |
| |
| This value determines how to group the document tree into Texinfo source |
| files. It must be a list of tuples ``(startdocname, targetname, title, |
| author, dir_entry, description, category, toctree_only)``, where the items |
| are: |
| |
| * *startdocname*: document name that is the "root" of the Texinfo file. All |
| documents referenced by it in TOC trees will be included in the Texinfo |
| file too. (If you want only one Texinfo file, use your |
| :confval:`master_doc` here.) |
| * *targetname*: file name (no extension) of the Texinfo file in the output |
| directory. |
| * *title*: Texinfo document title. Can be empty to use the title of the |
| *startdoc*. Inserted as Texinfo markup, so special characters like @ and |
| {} will need to be escaped to be inserted literally. |
| * *author*: Author for the Texinfo document. Inserted as Texinfo markup. |
| Use ``@*`` to separate multiple authors, as in: ``'John@*Sarah'``. |
| * *dir_entry*: The name that will appear in the top-level ``DIR`` menu file. |
| * *description*: Descriptive text to appear in the top-level ``DIR`` menu |
| 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* |
| 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 |
| output. |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: texinfo_appendices |
| |
| A list of document names to append as an appendix to all manuals. |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: texinfo_domain_indices |
| |
| If true, generate domain-specific indices in addition to the general index. |
| For e.g. the Python domain, this is the global module index. Default is |
| ``True``. |
| |
| This value can be a bool or a list of index names that should be generated, |
| like for :confval:`html_domain_indices`. |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: texinfo_show_urls |
| |
| Control how to display URL addresses. |
| |
| * ``'footnote'`` -- display URLs in footnotes (default) |
| * ``'no'`` -- do not display URLs |
| * ``'inline'`` -- display URLs inline in parentheses |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: texinfo_no_detailmenu |
| |
| If true, do not generate a ``@detailmenu`` in the "Top" node's menu |
| containing entries for each sub-node in the document. Default is ``False``. |
| |
| .. versionadded:: 1.2 |
| |
| .. confval:: texinfo_elements |
| |
| A dictionary that contains Texinfo snippets that override those Sphinx |
| usually puts into the generated ``.texi`` files. |
| |
| * Keys that you may want to override include: |
| |
| ``'paragraphindent'`` |
| Number of spaces to indent the first line of each paragraph, default |
| ``2``. Specify ``0`` for no indentation. |
| |
| ``'exampleindent'`` |
| Number of spaces to indent the lines for examples or literal blocks, |
| default ``4``. Specify ``0`` for no indentation. |
| |
| ``'preamble'`` |
| Texinfo markup inserted near the beginning of the file. |
| |
| ``'copying'`` |
| Texinfo markup inserted within the ``@copying`` block and displayed |
| after the title. The default value consists of a simple title page |
| identifying the project. |
| |
| * Keys that are set by other options and therefore should not be overridden |
| are: |
| |
| ``'author'`` |
| ``'body'`` |
| ``'date'`` |
| ``'direntry'`` |
| ``'filename'`` |
| ``'project'`` |
| ``'release'`` |
| ``'title'`` |
| |
| .. versionadded:: 1.1 |
| |
| |
| Options for the linkcheck builder |
| --------------------------------- |
| |
| .. confval:: linkcheck_ignore |
| |
| A list of regular expressions that match URIs that should not be checked |
| when doing a ``linkcheck`` build. Example:: |
| |
| linkcheck_ignore = [r'http://localhost:\d+/'] |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: linkcheck_timeout |
| |
| A timeout value, in seconds, for the linkcheck builder. **Only works in |
| Python 2.6 and higher.** The default is to use Python's global socket |
| timeout. |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: linkcheck_workers |
| |
| The number of worker threads to use when checking links. Default is 5 |
| threads. |
| |
| .. versionadded:: 1.1 |
| |
| .. confval:: linkcheck_anchors |
| |
| 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 |
| |
| |
| Options for the XML builder |
| --------------------------- |
| |
| .. confval:: xml_pretty |
| |
| If true, pretty-print the XML. Default is ``True``. |
| |
| .. versionadded:: 1.2 |
| |
| |
| .. rubric:: Footnotes |
| |
| .. [1] A note on available globbing syntax: you can use the standard shell |
| constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that |
| these all don't match slashes. A double star ``**`` can be used to match |
| any sequence of characters *including* slashes. |