mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge branch 'master' into refactor_latex_footnotes
This commit is contained in:
Takeshi KOMIYA
GitHub
commit
8febb09373
10
CHANGES
10
CHANGES
@ -23,6 +23,11 @@ Incompatible changes
|
||||
:py:meth:`.Sphinx.add_transform()`
|
||||
* #4827: All ``substitution_definition`` nodes are removed from doctree on
|
||||
reading phase
|
||||
* ``docutils.conf`` on ``$HOME`` and ``/etc`` directories are ignored. Only
|
||||
``docutils.conf`` on confdir is refered.
|
||||
* #789: ``:samp:`` role supports to escape curly braces with backslash
|
||||
* #4811: The files under :confval:`html_static_path` are excluded from source
|
||||
files.
|
||||
|
||||
Deprecated
|
||||
----------
|
||||
@ -48,6 +53,8 @@ Deprecated
|
||||
* ``Config.check_types()`` is deprecated
|
||||
* ``Config.check_unicode()`` is deprecated
|
||||
* ``sphinx.application.CONFIG_FILENAME`` is deprecated
|
||||
* ``highlightlang`` directive is deprecated
|
||||
* ``env.read_doc()`` is deprecated
|
||||
* ``sphinx.writers.latex.Table.caption_footnotetexts`` is deprecated
|
||||
* ``sphinx.writers.latex.Table.header_footnotetexts`` is deprecated
|
||||
* ``sphinx.writers.latex.LaTeXWriter.footnotestack`` is deprecated
|
||||
@ -86,6 +93,7 @@ Features added
|
||||
:rst:role:`menuselection` (refs: #4830)
|
||||
* Add ``Config.read()`` classmethod to create a new config object from
|
||||
configuration file
|
||||
* #4866: Wrap graphviz diagrams in ``<div>`` tag
|
||||
|
||||
Bugs fixed
|
||||
----------
|
||||
@ -119,6 +127,8 @@ Features added
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
* #4924: html search: Upper characters problem in any other languages
|
||||
|
||||
Testing
|
||||
--------
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
:target: https://pypi.org/project/Sphinx/
|
||||
:alt: Package on PyPi
|
||||
|
||||
.. image:: https://readthedocs.org/projects/sphinx/badge/
|
||||
.. image:: https://readthedocs.org/projects/sphinx/badge/?version=master
|
||||
:target: http://www.sphinx-doc.org/
|
||||
:alt: Documentation Status
|
||||
|
||||
|
||||
@ -10,17 +10,17 @@ Sphinx documentation contents
|
||||
usage/installation
|
||||
usage/quickstart
|
||||
usage/restructuredtext/index
|
||||
usage/markdown
|
||||
usage/configuration
|
||||
|
||||
intro
|
||||
man/index
|
||||
builders
|
||||
config
|
||||
intl
|
||||
theming
|
||||
setuptools
|
||||
templating
|
||||
latex
|
||||
markdown
|
||||
extensions
|
||||
extdev/index
|
||||
websupport
|
||||
|
||||
@ -116,6 +116,11 @@ The following is a list of deprecated interface.
|
||||
- (will be) Removed
|
||||
- Alternatives
|
||||
|
||||
* - :rst:dir:`highlightlang`
|
||||
- 1.8
|
||||
- 4.0
|
||||
- :rst:dir:`highlight`
|
||||
|
||||
* - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
|
||||
- 1.8
|
||||
- 4.0
|
||||
@ -223,6 +228,11 @@ The following is a list of deprecated interface.
|
||||
- 3.0
|
||||
- ``Builder.read()``
|
||||
|
||||
* - ``BuildEnvironment.read_doc()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``Builder.read_doc()``
|
||||
|
||||
* - ``BuildEnvironment._read_serial()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
@ -233,6 +243,11 @@ The following is a list of deprecated interface.
|
||||
- 3.0
|
||||
- ``Builder.read()``
|
||||
|
||||
* - ``BuildEnvironment.write_doctree()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
- ``Builder.write_doctree()``
|
||||
|
||||
* - ``sphinx.locale.l_()``
|
||||
- 1.8
|
||||
- 3.0
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. highlightlang:: python
|
||||
.. highlight:: python
|
||||
|
||||
.. _latex:
|
||||
|
||||
|
||||
@ -1,45 +0,0 @@
|
||||
.. highlightlang:: python
|
||||
|
||||
.. _markdown:
|
||||
|
||||
Markdown support
|
||||
================
|
||||
|
||||
`Markdown <https://daringfireball.net/projects/markdown/>`__ is a lightweight markup language with a simplistic plain
|
||||
text formatting syntax.
|
||||
It exists in many syntactically different *flavors*.
|
||||
To support Markdown-based documentation, Sphinx can use
|
||||
`recommonmark <https://recommonmark.readthedocs.io/en/latest/index.html>`__.
|
||||
recommonmark is a Docutils bridge to `CommonMark-py <https://github.com/rtfd/CommonMark-py>`__, a
|
||||
Python package for parsing the `CommonMark <http://commonmark.org/>`__ Markdown flavor.
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
To configure your Sphinx project for Markdown support, proceed as follows:
|
||||
|
||||
#. Install recommonmark:
|
||||
|
||||
::
|
||||
|
||||
pip install recommonmark
|
||||
|
||||
#. Add the Markdown parser to the ``source_parsers`` configuration variable in your Sphinx configuration file:
|
||||
|
||||
::
|
||||
|
||||
source_parsers = {
|
||||
'.md': 'recommonmark.parser.CommonMarkParser',
|
||||
}
|
||||
|
||||
You can replace `.md` with a filename extension of your choice.
|
||||
|
||||
#. Add the Markdown filename extension to the ``source_suffix`` configuration variable:
|
||||
|
||||
::
|
||||
|
||||
source_suffix = ['.rst', '.md']
|
||||
|
||||
#. You can further configure recommonmark to allow custom syntax that standard CommonMark doesn't support. Read more in
|
||||
the `recommonmark documentation <https://recommonmark.readthedocs.io/en/latest/auto_structify.html>`__.
|
||||
@ -1,4 +1,4 @@
|
||||
.. highlightlang:: python
|
||||
.. highlight:: python
|
||||
|
||||
HTML theming support
|
||||
====================
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
.. highlightlang:: python
|
||||
.. highlight:: python
|
||||
|
||||
.. _build-config:
|
||||
|
||||
The build configuration file
|
||||
============================
|
||||
=============
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. module:: conf
|
||||
:synopsis: Build configuration file.
|
||||
@ -14,11 +15,10 @@ and contains (almost) all configuration needed to customize Sphinx input
|
||||
and output behavior.
|
||||
|
||||
An optional file `docutils.conf`_ can be added to the configuration
|
||||
directory to adjust `Docutils`_ configuration if not otherwise overriden or
|
||||
directory to adjust `Docutils`_ configuration if not otherwise overridden or
|
||||
set by Sphinx.
|
||||
|
||||
.. _`docutils`: http://docutils.sourceforge.net/
|
||||
|
||||
.. _`docutils.conf`: http://docutils.sourceforge.net/docs/user/config.html
|
||||
|
||||
The configuration file is executed as Python code at build time (using
|
||||
@ -36,8 +36,8 @@ Important points to note:
|
||||
``"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.
|
||||
* 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
|
||||
@ -82,8 +82,8 @@ General configuration
|
||||
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.
|
||||
The configuration file itself can be an extension; for that, you only need
|
||||
to provide a :func:`setup` function in it.
|
||||
|
||||
.. confval:: source_suffix
|
||||
|
||||
@ -136,7 +136,8 @@ General configuration
|
||||
|
||||
.. note::
|
||||
|
||||
Read more about how to use Markdown with Sphinx at :ref:`markdown`.
|
||||
Refer to :doc:`/usage/markdown` for more information on using Markdown
|
||||
with Sphinx.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
@ -151,9 +152,10 @@ General configuration
|
||||
|
||||
.. 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.
|
||||
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:
|
||||
|
||||
@ -181,10 +183,10 @@ General configuration
|
||||
|
||||
.. 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
|
||||
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
|
||||
@ -247,9 +249,9 @@ General configuration
|
||||
|
||||
.. 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.
|
||||
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.
|
||||
|
||||
@ -302,8 +304,8 @@ General configuration
|
||||
.. 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.
|
||||
compare it with its version and refuse to build if it is too old. Default
|
||||
is no requirement.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
@ -312,8 +314,8 @@ General configuration
|
||||
|
||||
.. confval:: needs_extensions
|
||||
|
||||
This value can be a dictionary specifying version requirements for extensions
|
||||
in :confval:`extensions`, e.g. ``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.
|
||||
@ -351,10 +353,10 @@ General configuration
|
||||
|
||||
.. 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')``.
|
||||
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
|
||||
|
||||
@ -366,8 +368,8 @@ General configuration
|
||||
|
||||
.. note::
|
||||
|
||||
The LaTeX builder always assigns numbers whether this option is enabled or
|
||||
not.
|
||||
The LaTeX builder always assigns numbers whether this option is enabled
|
||||
or not.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
@ -375,7 +377,7 @@ General configuration
|
||||
|
||||
A dictionary mapping ``'figure'``, ``'table'``, ``'code-block'`` and
|
||||
``'section'`` to strings that are used for format of figure numbers.
|
||||
As a special character, `%s` will be replaced to figure number.
|
||||
As a special character, ``%s`` will be replaced to figure number.
|
||||
|
||||
Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for
|
||||
``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section'`` for
|
||||
@ -474,6 +476,7 @@ General configuration
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
|
||||
Project information
|
||||
-------------------
|
||||
|
||||
@ -513,7 +516,7 @@ Project information
|
||||
* 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,
|
||||
The default is now :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).
|
||||
|
||||
@ -527,7 +530,7 @@ Project information
|
||||
|
||||
.. versionchanged:: 1.4
|
||||
The default is now ``'default'``. It is similar to ``'python3'``;
|
||||
it is mostly a superset of ``'python'``. but it fallbacks to
|
||||
it is mostly a superset of ``'python'`` but it fallbacks to
|
||||
``'none'`` without warning if failed. ``'python3'`` and other
|
||||
languages will emit warning if failed. If you prefer Python 2
|
||||
only highlighting, you can set it back to ``'python'``.
|
||||
@ -544,7 +547,8 @@ Project information
|
||||
.. confval:: pygments_style
|
||||
|
||||
The style name to use for Pygments highlighting of source code. If not set,
|
||||
either the theme's default style or ``'sphinx'`` is selected for HTML output.
|
||||
either the theme's default style or ``'sphinx'`` is selected for HTML
|
||||
output.
|
||||
|
||||
.. versionchanged:: 0.3
|
||||
If the value is a fully-qualified name of a custom Pygments style class,
|
||||
@ -579,8 +583,8 @@ Project information
|
||||
|
||||
.. 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.
|
||||
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
|
||||
|
||||
@ -767,6 +771,7 @@ documentation on :ref:`intl` for details.
|
||||
.. versionchanged:: 1.5
|
||||
Added ``{path}`` and ``{basename}`` tokens.
|
||||
|
||||
|
||||
.. _html-options:
|
||||
|
||||
Options for HTML output
|
||||
@ -778,7 +783,7 @@ 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 ``'alabaster'``.
|
||||
theming </theming>`. The default is ``'alabaster'``.
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
@ -800,11 +805,12 @@ that use Sphinx's HTMLWriter class.
|
||||
|
||||
.. 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.
|
||||
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
|
||||
|
||||
@ -815,8 +821,8 @@ that use Sphinx's HTMLWriter class.
|
||||
|
||||
.. 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
|
||||
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
|
||||
@ -877,6 +883,9 @@ that use Sphinx's HTMLWriter class.
|
||||
named :file:`default.css` will overwrite the theme's
|
||||
:file:`default.css`.
|
||||
|
||||
As these files are not meant to be built, they are automatically excluded
|
||||
from source files.
|
||||
|
||||
.. note::
|
||||
|
||||
For security reason, dotfiles under ``html_static_path`` will
|
||||
@ -895,6 +904,10 @@ that use Sphinx's HTMLWriter class.
|
||||
.. versionchanged:: 1.0
|
||||
The entries in :confval:`html_static_path` can now be single files.
|
||||
|
||||
.. versionchanged:: 1.8
|
||||
The files under :confval:`html_static_path` are excluded from source
|
||||
files.
|
||||
|
||||
.. confval:: html_extra_path
|
||||
|
||||
A list of paths that contain extra files not directly related to
|
||||
@ -903,15 +916,15 @@ that use Sphinx's HTMLWriter class.
|
||||
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`.
|
||||
As these files are not meant to be built, they are automatically excluded
|
||||
from source files.
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
.. versionchanged:: 1.4
|
||||
The dotfiles in the extra directory will be copied to the output directory.
|
||||
And it refers :confval:`exclude_patterns` on copying extra files and
|
||||
directories, and ignores if path matches to patterns.
|
||||
The dotfiles in the extra directory will be copied to the output
|
||||
directory. And it refers :confval:`exclude_patterns` on copying extra
|
||||
files and directories, and ignores if path matches to patterns.
|
||||
|
||||
.. confval:: html_last_updated_fmt
|
||||
|
||||
@ -1066,12 +1079,12 @@ that use Sphinx's HTMLWriter class.
|
||||
|
||||
.. confval:: html_use_opensearch
|
||||
|
||||
If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ 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. ``"https://docs.python.org"``. The
|
||||
default is ``''``.
|
||||
If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ 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.
|
||||
``"https://docs.python.org"``. The default is ``''``.
|
||||
|
||||
.. confval:: html_file_suffix
|
||||
|
||||
@ -1178,18 +1191,19 @@ that use Sphinx's HTMLWriter class.
|
||||
The Japanese support has these options:
|
||||
|
||||
:type:
|
||||
_`type` is dotted module path string to specify Splitter implementation which
|
||||
should be derived from :class:`sphinx.search.ja.BaseSplitter`.
|
||||
If not specified or None is specified, ``'sphinx.search.ja.DefaultSplitter'`` will
|
||||
be used.
|
||||
_`type` is dotted module path string to specify Splitter implementation
|
||||
which should be derived from :class:`sphinx.search.ja.BaseSplitter`. If
|
||||
not specified or None is specified,
|
||||
``'sphinx.search.ja.DefaultSplitter'`` will be used.
|
||||
|
||||
You can choose from these modules:
|
||||
|
||||
:'sphinx.search.ja.DefaultSplitter':
|
||||
TinySegmenter algorithm. This is default splitter.
|
||||
:'sphinx.search.ja.MeCabSplitter':
|
||||
MeCab binding. To use this splitter, 'mecab' python binding or dynamic link
|
||||
library ('libmecab.so' for linux, 'libmecab.dll' for windows) is required.
|
||||
MeCab binding. To use this splitter, 'mecab' python binding or dynamic
|
||||
link library ('libmecab.so' for linux, 'libmecab.dll' for windows) is
|
||||
required.
|
||||
:'sphinx.search.ja.JanomeSplitter':
|
||||
Janome binding. To use this splitter,
|
||||
`Janome <https://pypi.org/project/Janome/>`_ is required.
|
||||
@ -1199,7 +1213,6 @@ that use Sphinx's HTMLWriter class.
|
||||
To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are
|
||||
also acceptable.
|
||||
|
||||
|
||||
Other option values depend on splitter value which you choose.
|
||||
|
||||
Options for ``'mecab'``:
|
||||
@ -1208,8 +1221,8 @@ that use Sphinx's HTMLWriter class.
|
||||
:dict:
|
||||
_`dict option` is the dictionary to use for the MeCab algorithm.
|
||||
:lib:
|
||||
_`lib option` is the library name for finding the MeCab library via ctypes if
|
||||
the Python binding is not installed.
|
||||
_`lib option` is the library name for finding the MeCab library via
|
||||
ctypes if the Python binding is not installed.
|
||||
|
||||
For example::
|
||||
|
||||
@ -1221,17 +1234,17 @@ that use Sphinx's HTMLWriter class.
|
||||
}
|
||||
|
||||
Options for ``'janome'``:
|
||||
:user_dic: _`user_dic option` is the user dictionary file path for Janome.
|
||||
:user_dic:
|
||||
_`user_dic option` is the user dictionary file path for Janome.
|
||||
:user_dic_enc:
|
||||
_`user_dic_enc option` is the encoding for the user dictionary file specified by
|
||||
``user_dic`` option. Default is 'utf8'.
|
||||
_`user_dic_enc option` is the encoding for the user dictionary file
|
||||
specified by ``user_dic`` option. Default is 'utf8'.
|
||||
|
||||
.. versionadded:: 1.1
|
||||
|
||||
.. versionchanged:: 1.4
|
||||
html_search_options for Japanese is re-organized and any custom splitter can be
|
||||
used by `type`_ settings.
|
||||
|
||||
html_search_options for Japanese is re-organized and any custom splitter
|
||||
can be used by `type`_ settings.
|
||||
|
||||
The Chinese support has these options:
|
||||
|
||||
@ -1257,10 +1270,12 @@ that use Sphinx's HTMLWriter class.
|
||||
|
||||
.. confval:: html_experimental_html5_writer
|
||||
|
||||
Output is processed with HTML5 writer. This feature needs docutils 0.13 or newer. Default is ``False``.
|
||||
Output is processed with HTML5 writer. This feature needs docutils 0.13 or
|
||||
newer. Default is ``False``.
|
||||
|
||||
.. versionadded:: 1.6
|
||||
|
||||
|
||||
.. _htmlhelp-options:
|
||||
|
||||
Options for HTML help output
|
||||
@ -1270,6 +1285,7 @@ Options for HTML help output
|
||||
|
||||
Output file base name for HTML help builder. Default is ``'pydoc'``.
|
||||
|
||||
|
||||
.. _applehelp-options:
|
||||
|
||||
Options for Apple Help output
|
||||
@ -1315,8 +1331,8 @@ HTML builder, so the HTML options also apply where appropriate.
|
||||
|
||||
.. confval:: applehelp_icon
|
||||
|
||||
The help bundle icon file, or ``None`` for no icon. According to Apple’s
|
||||
documentation, this should be a 16-by-16 pixel version of the application’s
|
||||
The help bundle icon file, or ``None`` for no icon. According to Apple's
|
||||
documentation, this should be a 16-by-16 pixel version of the application's
|
||||
icon with a transparent background, saved as a PNG file.
|
||||
|
||||
.. confval:: applehelp_kb_product
|
||||
@ -1330,14 +1346,14 @@ HTML builder, so the HTML options also apply where appropriate.
|
||||
e.g. ``https://example.com/kbsearch.py?p='product'&q='query'&l='lang'``.
|
||||
Help Viewer will replace the values ``'product'``, ``'query'`` and
|
||||
``'lang'`` at runtime with the contents of :confval:`applehelp_kb_product`,
|
||||
the text entered by the user in the search box and the user’s system
|
||||
the text entered by the user in the search box and the user's system
|
||||
language respectively.
|
||||
|
||||
Defaults to ``None`` for no remote search.
|
||||
|
||||
.. confval:: applehelp_remote_url
|
||||
|
||||
The URL for remote content. You can place a copy of your Help Book’s
|
||||
The URL for remote content. You can place a copy of your Help Book's
|
||||
``Resources`` folder at this location and Help Viewer will attempt to use
|
||||
it to fetch updated content.
|
||||
|
||||
@ -1452,8 +1468,8 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
|
||||
|
||||
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.
|
||||
output is usually not wise. This defaults to ``'epub'``, a theme designed
|
||||
to save visual space.
|
||||
|
||||
.. confval:: epub_theme_options
|
||||
|
||||
@ -1500,9 +1516,9 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
|
||||
|
||||
.. 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 defaults to the
|
||||
:confval:`author` option.
|
||||
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 defaults to
|
||||
the :confval:`author` option.
|
||||
|
||||
.. confval:: epub_copyright
|
||||
|
||||
@ -1527,9 +1543,9 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
|
||||
|
||||
A unique identifier for the document. This is put in the Dublin Core
|
||||
metadata. You may use a
|
||||
`XML's Name format <https://www.w3.org/TR/REC-xml/#NT-NameStartChar>`_ string.
|
||||
You can't use hyphen, period, numbers as a first character.
|
||||
The default value is ``'unknown'``.
|
||||
`XML's Name format <https://www.w3.org/TR/REC-xml/#NT-NameStartChar>`_
|
||||
string. You can't use hyphen, period, numbers as a first character. The
|
||||
default value is ``'unknown'``.
|
||||
|
||||
.. confval:: epub_cover
|
||||
|
||||
@ -1683,12 +1699,14 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
|
||||
|
||||
.. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
|
||||
|
||||
|
||||
.. _latex-options:
|
||||
|
||||
Options for LaTeX output
|
||||
------------------------
|
||||
|
||||
These options influence LaTeX output. See further :doc:`latex`.
|
||||
These options influence LaTeX output. Refer to :doc:`/latex` for more
|
||||
information.
|
||||
|
||||
.. confval:: latex_engine
|
||||
|
||||
@ -1736,7 +1754,8 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
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'`` (backslashes must be Python-escaped to reach LaTeX).
|
||||
``'John \\and Sarah'`` (backslashes must be Python-escaped to reach
|
||||
LaTeX).
|
||||
* *documentclass*: Normally, one of ``'manual'`` or ``'howto'`` (provided
|
||||
by Sphinx and based on ``'report'``, resp. ``'article'``; Japanese
|
||||
documents use ``'jsbook'``, resp. ``'jreport'``.) "howto" (non-Japanese)
|
||||
@ -1748,7 +1767,8 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
* *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.
|
||||
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
|
||||
@ -1845,29 +1865,34 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
``'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'``.
|
||||
|
||||
``'pxunit'``
|
||||
the value of the ``px`` when used in image attributes ``width`` and
|
||||
``height``. The default value is ``'0.75bp'`` which achieves
|
||||
``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for
|
||||
example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter
|
||||
leads to TeX computing a more precise value, due to the smaller unit
|
||||
used in the specification); for ``72px=1in``,
|
||||
simply use ``'1bp'``; for ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
|
||||
used in the specification); for ``72px=1in``, simply use ``'1bp'``; for
|
||||
``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
``'sphinxsetup'``
|
||||
A comma separated list of ``key=value`` package options for the Sphinx
|
||||
LaTeX style, default empty. See :doc:`latex`.
|
||||
LaTeX style, default empty. See :doc:`/latex`.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
``'passoptionstopackages'``
|
||||
A string which will be positioned early in the preamble, designed to
|
||||
contain ``\\PassOptionsToPackage{options}{foo}`` commands. Default empty.
|
||||
|
||||
.. versionadded:: 1.4
|
||||
|
||||
``'babel'``
|
||||
"babel" package inclusion, default ``'\\usepackage{babel}'`` (the
|
||||
suitable document language string is passed as class option, and
|
||||
@ -1879,6 +1904,7 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
|
||||
.. versionchanged:: 1.6
|
||||
``'lualatex'`` uses same default setting as ``'xelatex'``
|
||||
|
||||
``'fontpkg'``
|
||||
Font package inclusion, default ``'\\usepackage{times}'`` (which uses
|
||||
Times for text, Helvetica for sans serif and Courier for code-blocks).
|
||||
@ -1908,12 +1934,15 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
the "Bjarne" style uses numbers spelled out in English). Other
|
||||
"fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
|
||||
"Bjornstrup". You can also set this to ``''`` to disable fncychap.
|
||||
|
||||
``'preamble'``
|
||||
Additional preamble content, default empty. See :doc:`latex`.
|
||||
Additional preamble content, default empty. See :doc:`/latex`.
|
||||
|
||||
``'atendofbody'``
|
||||
Additional document content (right before the indices), default empty.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
``'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
|
||||
@ -1922,6 +1951,7 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
and position figures strictly in the order they appear in the source.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
``'footer'``
|
||||
Additional footer content (before the indices), default empty.
|
||||
|
||||
@ -1938,6 +1968,7 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
.. versionadded:: 1.2
|
||||
.. versionchanged:: 1.6
|
||||
Added this documentation.
|
||||
|
||||
``'maxlistdepth'``
|
||||
LaTeX allows by default at most 6 levels for nesting list and
|
||||
quote-like environments, with at most 4 enumerated lists, and 4 bullet
|
||||
@ -1955,6 +1986,7 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
dedicated commands of this LaTeX package.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
``'inputenc'``
|
||||
"inputenc" package inclusion, defaults to
|
||||
``'\\usepackage[utf8]{inputenc}'`` when using pdflatex.
|
||||
@ -1963,10 +1995,12 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
.. versionchanged:: 1.4.3
|
||||
Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
|
||||
compilers.
|
||||
|
||||
``'cmappkg'``
|
||||
"cmap" package inclusion, default ``'\\usepackage{cmap}'``.
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
``'fontenc'``
|
||||
"fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``.
|
||||
|
||||
@ -1975,6 +2009,7 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
:confval:`latex_engine` is ``'xelatex'``.
|
||||
.. versionchanged:: 1.6
|
||||
``'lualatex'`` also uses ``fontspec`` per default.
|
||||
|
||||
``'geometry'``
|
||||
"geometry" package inclusion, the default definition is:
|
||||
|
||||
@ -2005,6 +2040,7 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
width will be set to an integer multiple of the *zenkaku* width, and
|
||||
the text height to an integer multiple of the baseline. See the
|
||||
:ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.
|
||||
|
||||
``'hyperref'``
|
||||
"hyperref" package inclusion; also loads package "hypcap" and issues
|
||||
``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is
|
||||
@ -2016,15 +2052,17 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
Previously this was done from inside :file:`sphinx.sty`.
|
||||
|
||||
``'maketitle'``
|
||||
"maketitle" call, default ``'\\maketitle'`` (but it has been
|
||||
redefined by the Sphinx ``manual`` and ``howto`` classes.) Override
|
||||
if you want to
|
||||
generate a differently-styled title page.
|
||||
if you want to generate a differently-styled title page.
|
||||
|
||||
``'releasename'``
|
||||
value that prefixes ``'release'`` element on title page, default
|
||||
``'Release'``. As for *title* and *author* used in the tuples of
|
||||
:confval:`latex_documents`, it is inserted as LaTeX markup.
|
||||
|
||||
``'tableofcontents'``
|
||||
"tableofcontents" call, default ``'\\sphinxtableofcontents'`` (it is a
|
||||
wrapper of unmodified ``\tableofcontents``, which may itself be
|
||||
@ -2037,6 +2075,7 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
Previously the meaning of ``\tableofcontents`` itself was modified
|
||||
by Sphinx. This created an incompatibility with dedicated packages
|
||||
modifying it also such as "tocloft" or "etoc".
|
||||
|
||||
``'transition'``
|
||||
Commands used to display transitions, default
|
||||
``'\n\n\\bigskip\\hrule\\bigskip\n\n'``. Override if you want to
|
||||
@ -2045,12 +2084,14 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
.. versionadded:: 1.2
|
||||
.. versionchanged:: 1.6
|
||||
Remove unneeded ``{}`` after ``\\hrule``.
|
||||
|
||||
``'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. For example
|
||||
``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
|
||||
index is full of long entries.
|
||||
|
||||
``'fvset'``
|
||||
Customization of ``fancyvrb`` LaTeX package. Defaults to
|
||||
``'\\fvset{fontsize=\\small}'``, because default font (Courier) used in
|
||||
@ -2061,6 +2102,7 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
one unified typeface family (Latin Modern OpenType).
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
* Keys that are set by other options and therefore should not be overridden
|
||||
are:
|
||||
|
||||
@ -2089,19 +2131,20 @@ These options influence LaTeX output. See further :doc:`latex`.
|
||||
|
||||
.. 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.
|
||||
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.
|
||||
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.
|
||||
This overrides the files which is provided from Sphinx such as
|
||||
``sphinx.sty``.
|
||||
|
||||
|
||||
.. _text-options:
|
||||
@ -2143,8 +2186,8 @@ These options influence text output.
|
||||
|
||||
.. confval:: text_secnumber_suffix
|
||||
|
||||
Suffix for section numbers in text output. Default: ``". "``. Set to ``" "``
|
||||
to suppress the final dot on section numbers.
|
||||
Suffix for section numbers in text output. Default: ``". "``. Set to
|
||||
``" "`` to suppress the final dot on section numbers.
|
||||
|
||||
.. versionadded:: 1.7
|
||||
|
||||
@ -2162,20 +2205,27 @@ These options influence manual page output.
|
||||
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.
|
||||
*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
|
||||
|
||||
@ -2200,27 +2250,38 @@ These options influence Texinfo output.
|
||||
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.
|
||||
*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
|
||||
|
||||
@ -2306,7 +2367,8 @@ builder, the HTML options also apply where appropriate.
|
||||
|
||||
.. confval:: qthelp_basename
|
||||
|
||||
The basename for the qthelp file. It defaults to the :confval:`project` name.
|
||||
The basename for the qthelp file. It defaults to the :confval:`project`
|
||||
name.
|
||||
|
||||
.. confval:: qthelp_namespace
|
||||
|
||||
@ -2371,7 +2433,7 @@ Options for the linkcheck builder
|
||||
A list of regular expressions that match URIs that should skip checking
|
||||
the validity of anchors in links. This allows skipping entire sites, where
|
||||
anchors are used to control dynamic pages, or just specific anchors within
|
||||
a page, where javascript is used to add anchors dynamically, or use the
|
||||
a page, where JavaScript is used to add anchors dynamically, or use the
|
||||
fragment as part of to trigger an internal REST request. Default is
|
||||
``["/#!"]``.
|
||||
|
||||
@ -2392,8 +2454,8 @@ Options for the XML builder
|
||||
|
||||
.. [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.
|
||||
these all don't match slashes. A double star ``**`` can be used to
|
||||
match any sequence of characters *including* slashes.
|
||||
|
||||
|
||||
.. _cpp-config:
|
||||
@ -2403,29 +2465,32 @@ Options for the C++ domain
|
||||
|
||||
.. confval:: cpp_index_common_prefix
|
||||
|
||||
A list of prefixes that will be ignored when sorting C++ objects in the global index.
|
||||
For example ``['awesome_lib::']``.
|
||||
A list of prefixes that will be ignored when sorting C++ objects in the
|
||||
global index. For example ``['awesome_lib::']``.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
.. confval:: cpp_id_attributes
|
||||
|
||||
A list of strings that the parser additionally should accept as attributes.
|
||||
This can for example be used when attributes have been ``#define`` d for portability.
|
||||
This can for example be used when attributes have been ``#define`` d for
|
||||
portability.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
.. confval:: cpp_paren_attributes
|
||||
|
||||
A list of strings that the parser additionally should accept as attributes with one argument.
|
||||
That is, if ``my_align_as`` is in the list, then ``my_align_as(X)`` is parsed as an attribute
|
||||
for all strings ``X`` that have balanced brances (``()``, ``[]``, and ``{}``).
|
||||
This can for example be used when attributes have been ``#define`` d for portability.
|
||||
A list of strings that the parser additionally should accept as attributes
|
||||
with one argument. That is, if ``my_align_as`` is in the list, then
|
||||
``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have
|
||||
balanced brances (``()``, ``[]``, and ``{}``). This can for example be used
|
||||
when attributes have been ``#define`` d for portability.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
|
||||
Example of configuration file
|
||||
=============================
|
||||
|
||||
.. literalinclude:: _static/conf.py.txt
|
||||
.. literalinclude:: /_static/conf.py.txt
|
||||
:language: python
|
||||
47
doc/usage/markdown.rst
Normal file
47
doc/usage/markdown.rst
Normal file
@ -0,0 +1,47 @@
|
||||
.. highlight:: python
|
||||
|
||||
.. _markdown:
|
||||
|
||||
========
|
||||
Markdown
|
||||
========
|
||||
|
||||
`Markdown`__ is a lightweight markup language with a simplistic plain text
|
||||
formatting syntax. It exists in many syntactically different *flavors*. To
|
||||
support Markdown-based documentation, Sphinx can use `recommonmark`__.
|
||||
recommonmark is a Docutils bridge to `CommonMark-py`__, a Python package for
|
||||
parsing the `CommonMark`__ Markdown flavor.
|
||||
|
||||
__ https://daringfireball.net/projects/markdown/
|
||||
__ https://recommonmark.readthedocs.io/en/latest/index.html
|
||||
__ https://github.com/rtfd/CommonMark-py
|
||||
__ http://commonmark.org/
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
To configure your Sphinx project for Markdown support, proceed as follows:
|
||||
|
||||
#. Install *recommonmark*::
|
||||
|
||||
pip install recommonmark
|
||||
|
||||
#. Add the Markdown parser to the ``source_parsers`` configuration variable in
|
||||
your Sphinx configuration file::
|
||||
|
||||
source_parsers = {
|
||||
'.md': 'recommonmark.parser.CommonMarkParser',
|
||||
}
|
||||
|
||||
You can replace ``.md`` with a filename extension of your choice.
|
||||
|
||||
#. Add the Markdown filename extension to the ``source_suffix`` configuration
|
||||
variable::
|
||||
|
||||
source_suffix = ['.rst', '.md']
|
||||
|
||||
#. You can further configure *recommonmark* to allow custom syntax that
|
||||
standard *CommonMark* doesn't support. Read more in the `recommonmark
|
||||
documentation`__.
|
||||
|
||||
__ https://recommonmark.readthedocs.io/en/latest/auto_structify.html
|
||||
@ -236,7 +236,8 @@ so on. The file is saved in UTF-8 by default, as indicated by the encoding
|
||||
declaration in the first line. If you use non-ASCII characters in any string
|
||||
value, you need to use Python Unicode strings (like ``project = u'Exposé'``).
|
||||
|
||||
|more| See :ref:`build-config` for documentation of all available config values.
|
||||
|more| See :doc:`/usage/configuration` for documentation of all available
|
||||
config values.
|
||||
|
||||
|
||||
.. todo:: Move this entire doc to a different section
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. highlightlang:: rst
|
||||
.. highlight:: rst
|
||||
|
||||
.. _rst-primer:
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. highlightlang:: rst
|
||||
.. highlight:: rst
|
||||
|
||||
===========
|
||||
Field Lists
|
||||
|
||||
@ -406,6 +406,9 @@ different style:
|
||||
If you don't need the "variable part" indication, use the standard
|
||||
````code```` instead.
|
||||
|
||||
.. versionchanged:: 1.8
|
||||
Allowed to escape curly braces with backslash
|
||||
|
||||
There is also an :rst:role:`index` role to generate index entries.
|
||||
|
||||
The following roles generate external links:
|
||||
|
||||
@ -51,6 +51,7 @@ follow_imports = skip
|
||||
incremental = True
|
||||
check_untyped_defs = True
|
||||
warn_unused_ignores = True
|
||||
strict_optional = False
|
||||
|
||||
[tool:pytest]
|
||||
filterwarnings =
|
||||
|
||||
@ -9,19 +9,23 @@
|
||||
:license: BSD, see LICENSE for details.
|
||||
"""
|
||||
|
||||
import time
|
||||
import warnings
|
||||
from os import path
|
||||
|
||||
from docutils import nodes
|
||||
from six.moves import cPickle as pickle
|
||||
|
||||
from sphinx.deprecation import RemovedInSphinx20Warning
|
||||
from sphinx.environment import BuildEnvironment
|
||||
from sphinx.environment.adapters.asset import ImageAdapter
|
||||
from sphinx.errors import SphinxError
|
||||
from sphinx.io import read_doc
|
||||
from sphinx.locale import __
|
||||
from sphinx.util import i18n, import_object, logging, status_iterator
|
||||
from sphinx.util import i18n, import_object, logging, rst, status_iterator
|
||||
from sphinx.util.build_phase import BuildPhase
|
||||
from sphinx.util.console import bold # type: ignore
|
||||
from sphinx.util.docutils import sphinx_domains
|
||||
from sphinx.util.i18n import find_catalog
|
||||
from sphinx.util.osutil import SEP, ensuredir, relative_uri, relpath
|
||||
from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, \
|
||||
@ -478,7 +482,7 @@ class Builder(object):
|
||||
# remove all inventory entries for that file
|
||||
self.app.emit('env-purge-doc', self.env, docname)
|
||||
self.env.clear_doc(docname)
|
||||
self.env.read_doc(docname, self.app)
|
||||
self.read_doc(docname)
|
||||
|
||||
def _read_parallel(self, docnames, nproc):
|
||||
# type: (List[unicode], int) -> None
|
||||
@ -491,7 +495,7 @@ class Builder(object):
|
||||
# type: (List[unicode]) -> unicode
|
||||
self.env.app = self.app
|
||||
for docname in docs:
|
||||
self.env.read_doc(docname, self.app)
|
||||
self.read_doc(docname)
|
||||
# allow pickling self to send it back
|
||||
return BuildEnvironment.dumps(self.env)
|
||||
|
||||
@ -511,6 +515,47 @@ class Builder(object):
|
||||
logger.info(bold('waiting for workers...'))
|
||||
tasks.join()
|
||||
|
||||
def read_doc(self, docname):
|
||||
# type: (unicode) -> None
|
||||
"""Parse a file and add/update inventory entries for the doctree."""
|
||||
self.env.prepare_settings(docname)
|
||||
|
||||
# Add confdir/docutils.conf to dependencies list if exists
|
||||
docutilsconf = path.join(self.confdir, 'docutils.conf')
|
||||
if path.isfile(docutilsconf):
|
||||
self.env.note_dependency(docutilsconf)
|
||||
|
||||
with sphinx_domains(self.env), rst.default_role(docname, self.config.default_role):
|
||||
doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
|
||||
|
||||
# store time of reading, for outdated files detection
|
||||
# (Some filesystems have coarse timestamp resolution;
|
||||
# therefore time.time() can be older than filesystem's timestamp.
|
||||
# For example, FAT32 has 2sec timestamp resolution.)
|
||||
self.env.all_docs[docname] = max(time.time(),
|
||||
path.getmtime(self.env.doc2path(docname)))
|
||||
|
||||
# cleanup
|
||||
self.env.temp_data.clear()
|
||||
self.env.ref_context.clear()
|
||||
|
||||
self.write_doctree(docname, doctree)
|
||||
|
||||
def write_doctree(self, docname, doctree):
|
||||
# type: (unicode, nodes.Node) -> None
|
||||
"""Write the doctree to a file."""
|
||||
# make it picklable
|
||||
doctree.reporter = None
|
||||
doctree.transformer = None
|
||||
doctree.settings.warning_stream = None
|
||||
doctree.settings.env = None
|
||||
doctree.settings.record_dependencies = None
|
||||
|
||||
doctree_filename = self.env.doc2path(docname, self.env.doctreedir, '.doctree')
|
||||
ensuredir(path.dirname(doctree_filename))
|
||||
with open(doctree_filename, 'wb') as f:
|
||||
pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
|
||||
|
||||
def write(self, build_docnames, updated_docnames, method='update'):
|
||||
# type: (Iterable[unicode], Sequence[unicode], unicode) -> None
|
||||
if build_docnames is None or build_docnames == ['__all__']:
|
||||
|
||||
@ -355,7 +355,7 @@ class StandaloneHTMLBuilder(Builder):
|
||||
continue
|
||||
|
||||
if '://' not in filename:
|
||||
filename = path.join('_static', filename)
|
||||
filename = posixpath.join('_static', filename)
|
||||
|
||||
self.css_files.append(Stylesheet(filename, **attrs)) # type: ignore
|
||||
|
||||
@ -411,7 +411,7 @@ class StandaloneHTMLBuilder(Builder):
|
||||
|
||||
def get_asset_paths(self):
|
||||
# type: () -> List[unicode]
|
||||
return self.config.html_extra_path
|
||||
return self.config.html_extra_path + self.config.html_static_path
|
||||
|
||||
def render_partial(self, node):
|
||||
# type: (nodes.Nodes) -> Dict[unicode, unicode]
|
||||
|
||||
@ -269,7 +269,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder):
|
||||
resourcedir = root.startswith((staticdir, imagesdir))
|
||||
for fn in sorted(files):
|
||||
if (resourcedir and not fn.endswith('.js')) or fn.endswith('.html'):
|
||||
filename = path.join(root, fn)[olen:]
|
||||
filename = posixpath.join(root, fn)[olen:]
|
||||
project_files.append(filename)
|
||||
|
||||
return project_files
|
||||
|
||||
@ -293,7 +293,8 @@ def build_main(argv=sys.argv[1:]): # type: ignore
|
||||
|
||||
app = None
|
||||
try:
|
||||
with patch_docutils(), docutils_namespace():
|
||||
confdir = args.confdir or args.sourcedir
|
||||
with patch_docutils(confdir), docutils_namespace():
|
||||
app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
|
||||
args.doctreedir, args.builder, confoverrides, status,
|
||||
warning, args.freshenv, args.warningiserror,
|
||||
|
||||
@ -9,6 +9,7 @@
|
||||
|
||||
import codecs
|
||||
import sys
|
||||
import warnings
|
||||
from difflib import unified_diff
|
||||
|
||||
from docutils import nodes
|
||||
@ -17,6 +18,7 @@ from docutils.statemachine import ViewList
|
||||
from six import text_type
|
||||
|
||||
from sphinx import addnodes
|
||||
from sphinx.deprecation import RemovedInSphinx40Warning
|
||||
from sphinx.locale import __
|
||||
from sphinx.util import logging
|
||||
from sphinx.util import parselinenos
|
||||
@ -59,6 +61,17 @@ class Highlight(SphinxDirective):
|
||||
linenothreshold=linenothreshold)]
|
||||
|
||||
|
||||
class HighlightLang(Highlight):
|
||||
"""highlightlang directive (deprecated)"""
|
||||
|
||||
def run(self):
|
||||
# type: () -> List[nodes.Node]
|
||||
warnings.warn('highlightlang directive is deprecated. '
|
||||
'Please use highlight directive instead.',
|
||||
RemovedInSphinx40Warning)
|
||||
return Highlight.run(self)
|
||||
|
||||
|
||||
def dedent_lines(lines, dedent, location=None):
|
||||
# type: (List[unicode], int, Any) -> List[unicode]
|
||||
if not dedent:
|
||||
@ -462,7 +475,7 @@ class LiteralInclude(SphinxDirective):
|
||||
def setup(app):
|
||||
# type: (Sphinx) -> Dict[unicode, Any]
|
||||
directives.register_directive('highlight', Highlight)
|
||||
directives.register_directive('highlightlang', Highlight) # old
|
||||
directives.register_directive('highlightlang', HighlightLang)
|
||||
directives.register_directive('code-block', CodeBlock)
|
||||
directives.register_directive('sourcecode', CodeBlock)
|
||||
directives.register_directive('literalinclude', LiteralInclude)
|
||||
|
||||
@ -12,14 +12,12 @@
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
import time
|
||||
import types
|
||||
import warnings
|
||||
from collections import defaultdict
|
||||
from copy import copy
|
||||
from os import path
|
||||
|
||||
from docutils.frontend import OptionParser
|
||||
from docutils.utils import Reporter, get_source_line
|
||||
from six import BytesIO, class_types, next
|
||||
from six.moves import cPickle as pickle
|
||||
@ -29,16 +27,15 @@ from sphinx.deprecation import RemovedInSphinx20Warning, RemovedInSphinx30Warnin
|
||||
from sphinx.environment.adapters.indexentries import IndexEntries
|
||||
from sphinx.environment.adapters.toctree import TocTree
|
||||
from sphinx.errors import SphinxError, ExtensionError
|
||||
from sphinx.io import read_doc
|
||||
from sphinx.locale import __
|
||||
from sphinx.transforms import SphinxTransformer
|
||||
from sphinx.util import get_matching_docs, FilenameUniqDict
|
||||
from sphinx.util import logging, rst
|
||||
from sphinx.util.docutils import sphinx_domains, WarningStream
|
||||
from sphinx.util import logging
|
||||
from sphinx.util.docutils import WarningStream
|
||||
from sphinx.util.i18n import find_catalog_files
|
||||
from sphinx.util.matching import compile_matchers
|
||||
from sphinx.util.nodes import is_translatable
|
||||
from sphinx.util.osutil import SEP, ensuredir, relpath
|
||||
from sphinx.util.osutil import SEP, relpath
|
||||
from sphinx.util.websupport import is_commentable
|
||||
|
||||
if False:
|
||||
@ -556,33 +553,6 @@ class BuildEnvironment(object):
|
||||
self.temp_data['default_domain'] = \
|
||||
self.domains.get(self.config.primary_domain)
|
||||
|
||||
def read_doc(self, docname, app=None):
|
||||
# type: (unicode, Sphinx) -> None
|
||||
"""Parse a file and add/update inventory entries for the doctree."""
|
||||
self.prepare_settings(docname)
|
||||
|
||||
docutilsconf = path.join(self.srcdir, 'docutils.conf')
|
||||
# read docutils.conf from source dir, not from current dir
|
||||
OptionParser.standard_config_files[1] = docutilsconf
|
||||
if path.isfile(docutilsconf):
|
||||
self.note_dependency(docutilsconf)
|
||||
|
||||
with sphinx_domains(self), rst.default_role(docname, self.config.default_role):
|
||||
doctree = read_doc(self.app, self, self.doc2path(docname))
|
||||
|
||||
# store time of reading, for outdated files detection
|
||||
# (Some filesystems have coarse timestamp resolution;
|
||||
# therefore time.time() can be older than filesystem's timestamp.
|
||||
# For example, FAT32 has 2sec timestamp resolution.)
|
||||
self.all_docs[docname] = max(
|
||||
time.time(), path.getmtime(self.doc2path(docname)))
|
||||
|
||||
# cleanup
|
||||
self.temp_data.clear()
|
||||
self.ref_context.clear()
|
||||
|
||||
self.write_doctree(docname, doctree)
|
||||
|
||||
# utilities to use while reading a document
|
||||
|
||||
@property
|
||||
@ -685,21 +655,6 @@ class BuildEnvironment(object):
|
||||
doctree.reporter = Reporter(self.doc2path(docname), 2, 5, stream=WarningStream())
|
||||
return doctree
|
||||
|
||||
def write_doctree(self, docname, doctree):
|
||||
# type: (unicode, nodes.Node) -> None
|
||||
"""Write the doctree to a file."""
|
||||
# make it picklable
|
||||
doctree.reporter = None
|
||||
doctree.transformer = None
|
||||
doctree.settings.warning_stream = None
|
||||
doctree.settings.env = None
|
||||
doctree.settings.record_dependencies = None
|
||||
|
||||
doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree')
|
||||
ensuredir(path.dirname(doctree_filename))
|
||||
with open(doctree_filename, 'wb') as f:
|
||||
pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
|
||||
|
||||
def get_and_resolve_doctree(self, docname, builder, doctree=None,
|
||||
prune_toctrees=True, includehidden=False):
|
||||
# type: (unicode, Builder, nodes.Node, bool, bool) -> nodes.Node
|
||||
@ -849,6 +804,19 @@ class BuildEnvironment(object):
|
||||
RemovedInSphinx30Warning)
|
||||
return self.app.builder._read_parallel(docnames, nproc)
|
||||
|
||||
def read_doc(self, docname, app=None):
|
||||
# type: (unicode, Sphinx) -> None
|
||||
warnings.warn('env.read_doc() is deprecated. Please use builder.read_doc() instead.',
|
||||
RemovedInSphinx30Warning)
|
||||
self.app.builder.read_doc(docname)
|
||||
|
||||
def write_doctree(self, docname, doctree):
|
||||
# type: (unicode, nodes.Node) -> None
|
||||
warnings.warn('env.write_doctree() is deprecated. '
|
||||
'Please use builder.write_doctree() instead.',
|
||||
RemovedInSphinx30Warning)
|
||||
self.app.builder.write_doctree(docname, doctree)
|
||||
|
||||
@property
|
||||
def _nitpick_ignore(self):
|
||||
# type: () -> List[unicode]
|
||||
|
||||
@ -290,21 +290,27 @@ def render_dot_html(self, node, code, options, prefix='graphviz',
|
||||
self.body.append('<div align="%s" class="align-%s">' %
|
||||
(node['align'], node['align']))
|
||||
if format == 'svg':
|
||||
svgtag = '''<object data="%s" type="image/svg+xml">
|
||||
<p class="warning">%s</p></object>\n''' % (fname, alt)
|
||||
self.body.append(svgtag)
|
||||
self.body.append('<div class="graphviz">')
|
||||
self.body.append('<object data="%s" type="image/svg+xml" %s>\n' %
|
||||
(fname, imgcss))
|
||||
self.body.append('<p class="warning">%s</p>' % alt)
|
||||
self.body.append('</object></div>\n')
|
||||
else:
|
||||
with codecs.open(outfn + '.map', 'r', encoding='utf-8') as mapfile: # type: ignore
|
||||
imgmap = ClickableMapDefinition(outfn + '.map', mapfile.read(), dot=code)
|
||||
if imgmap.clickable:
|
||||
# has a map
|
||||
self.body.append('<img src="%s" alt="%s" usemap="#%s" %s/>\n' %
|
||||
self.body.append('<div class="graphviz">')
|
||||
self.body.append('<img src="%s" alt="%s" usemap="#%s" %s/>' %
|
||||
(fname, alt, imgmap.id, imgcss))
|
||||
self.body.append('</div>\n')
|
||||
self.body.append(imgmap.generate_clickable_map())
|
||||
else:
|
||||
# nothing in image map
|
||||
self.body.append('<img src="%s" alt="%s" %s/>\n' %
|
||||
self.body.append('<div class="graphviz">')
|
||||
self.body.append('<img src="%s" alt="%s" %s/>' %
|
||||
(fname, alt, imgcss))
|
||||
self.body.append('</div>\n')
|
||||
if 'align' in node:
|
||||
self.body.append('</div>\n')
|
||||
|
||||
|
||||
@ -239,7 +239,7 @@ class InheritanceGraph(object):
|
||||
def get_all_class_names(self):
|
||||
# type: () -> List[unicode]
|
||||
"""Get all of the class names involved in the graph."""
|
||||
return [fullname for (_, fullname, _, _) in self.class_info] # type: ignore
|
||||
return [fullname for (_, fullname, _, _) in self.class_info]
|
||||
|
||||
# These are the default attrs for graphviz
|
||||
default_graph_attrs = {
|
||||
|
||||
@ -284,6 +284,7 @@ def menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
|
||||
|
||||
|
||||
_litvar_re = re.compile('{([^}]+)}')
|
||||
parens_re = re.compile(r'(\\*{|\\*})')
|
||||
|
||||
|
||||
def emph_literal_role(typ, rawtext, text, lineno, inliner,
|
||||
@ -296,17 +297,43 @@ def emph_literal_role(typ, rawtext, text, lineno, inliner,
|
||||
else:
|
||||
typ = typ.lower()
|
||||
|
||||
text = utils.unescape(text)
|
||||
pos = 0
|
||||
retnode = nodes.literal(role=typ.lower(), classes=[typ])
|
||||
for m in _litvar_re.finditer(text): # type: ignore
|
||||
if m.start() > pos:
|
||||
txt = text[pos:m.start()]
|
||||
retnode += nodes.Text(txt, txt)
|
||||
retnode += nodes.emphasis(m.group(1), m.group(1))
|
||||
pos = m.end()
|
||||
if pos < len(text):
|
||||
retnode += nodes.Text(text[pos:], text[pos:])
|
||||
parts = list(parens_re.split(utils.unescape(text)))
|
||||
stack = ['']
|
||||
for part in parts:
|
||||
matched = parens_re.match(part)
|
||||
if matched:
|
||||
backslashes = len(part) - 1
|
||||
if backslashes % 2 == 1: # escaped
|
||||
stack[-1] += "\\" * int((backslashes - 1) / 2) + part[-1]
|
||||
elif part[-1] == '{': # rparen
|
||||
stack[-1] += "\\" * int(backslashes / 2)
|
||||
if len(stack) >= 2 and stack[-2] == "{":
|
||||
# nested
|
||||
stack[-1] += "{"
|
||||
else:
|
||||
# start emphasis
|
||||
stack.append('{')
|
||||
stack.append('')
|
||||
else: # lparen
|
||||
stack[-1] += "\\" * int(backslashes / 2)
|
||||
if len(stack) == 3 and stack[1] == "{" and len(stack[2]) > 0:
|
||||
# emphasized word found
|
||||
if stack[0]:
|
||||
retnode += nodes.Text(stack[0], stack[0])
|
||||
retnode += nodes.emphasis(stack[2], stack[2])
|
||||
stack = ['']
|
||||
else:
|
||||
# emphasized word not found; the rparen is not a special symbol
|
||||
stack.append('}')
|
||||
stack = [''.join(stack)]
|
||||
else:
|
||||
stack[-1] += part
|
||||
if ''.join(stack):
|
||||
# remaining is treated as Text
|
||||
text = ''.join(stack)
|
||||
retnode += nodes.Text(text, text)
|
||||
|
||||
return [retnode], []
|
||||
|
||||
|
||||
|
||||
@ -135,4 +135,4 @@ class SearchDanish(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -378,4 +378,4 @@ class SearchSpanish(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -128,4 +128,4 @@ class SearchFinnish(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -242,4 +242,4 @@ class SearchHungarian(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -331,4 +331,4 @@ class SearchItalian(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -142,4 +142,4 @@ class SearchDutch(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -217,4 +217,4 @@ class SearchNorwegian(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -277,4 +277,4 @@ class SearchPortuguese(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -36,4 +36,4 @@ class SearchRomanian(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -266,4 +266,4 @@ class SearchRussian(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -154,4 +154,4 @@ class SearchSwedish(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -36,4 +36,4 @@ class SearchTurkish(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stemWord(word)
|
||||
return self.stemmer.stemWord(word.lower())
|
||||
|
||||
@ -259,4 +259,4 @@ class SearchChinese(SearchLanguage):
|
||||
|
||||
def stem(self, word):
|
||||
# type: (unicode) -> unicode
|
||||
return self.stemmer.stem(word)
|
||||
return self.stemmer.stem(word.lower())
|
||||
|
||||
@ -16,7 +16,7 @@ from __future__ import print_function
|
||||
import os
|
||||
import sys
|
||||
from distutils.cmd import Command
|
||||
from distutils.errors import DistutilsOptionError, DistutilsExecError # type: ignore
|
||||
from distutils.errors import DistutilsOptionError, DistutilsExecError
|
||||
|
||||
from six import StringIO, string_types
|
||||
|
||||
@ -179,7 +179,8 @@ class BuildDoc(Command):
|
||||
app = None
|
||||
|
||||
try:
|
||||
with patch_docutils(), docutils_namespace():
|
||||
confdir = self.config_dir or self.source_dir
|
||||
with patch_docutils(confdir), docutils_namespace():
|
||||
app = Sphinx(self.source_dir, self.config_dir,
|
||||
builder_target_dir, self.doctree_dir,
|
||||
builder, confoverrides, status_stream,
|
||||
|
||||
@ -10,16 +10,17 @@
|
||||
"""
|
||||
from __future__ import absolute_import
|
||||
|
||||
import os
|
||||
import re
|
||||
import types
|
||||
import warnings
|
||||
from contextlib import contextmanager
|
||||
from copy import copy
|
||||
from distutils.version import LooseVersion
|
||||
from os import path
|
||||
|
||||
import docutils
|
||||
from docutils import nodes
|
||||
from docutils.languages import get_language
|
||||
from docutils.parsers.rst import Directive, directives, roles, convert_directive_function
|
||||
from docutils.statemachine import StateMachine
|
||||
from docutils.utils import Reporter
|
||||
@ -34,7 +35,7 @@ report_re = re.compile('^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(
|
||||
|
||||
if False:
|
||||
# For type annotation
|
||||
from typing import Any, Callable, Generator, Iterator, List, Set, Tuple # NOQA
|
||||
from typing import Any, Callable, Generator, List, Set, Tuple # NOQA
|
||||
from docutils.statemachine import State, ViewList # NOQA
|
||||
from sphinx.config import Config # NOQA
|
||||
from sphinx.environment import BuildEnvironment # NOQA
|
||||
@ -47,7 +48,7 @@ additional_nodes = set() # type: Set[nodes.Node]
|
||||
|
||||
@contextmanager
|
||||
def docutils_namespace():
|
||||
# type: () -> Iterator[None]
|
||||
# type: () -> Generator[None, None, None]
|
||||
"""Create namespace for reST parsers."""
|
||||
try:
|
||||
_directives = copy(directives._directives)
|
||||
@ -94,29 +95,53 @@ def unregister_node(node):
|
||||
delattr(nodes.SparseNodeVisitor, 'depart_' + node.__name__)
|
||||
|
||||
|
||||
def patched_get_language(language_code, reporter=None):
|
||||
# type: (unicode, Reporter) -> Any
|
||||
"""A wrapper for docutils.languages.get_language().
|
||||
@contextmanager
|
||||
def patched_get_language():
|
||||
# type: () -> Generator[None, None, None]
|
||||
"""Patch docutils.languages.get_language() temporarily.
|
||||
|
||||
This ignores the second argument ``reporter`` to suppress warnings.
|
||||
refs: https://github.com/sphinx-doc/sphinx/issues/3788
|
||||
"""
|
||||
return get_language(language_code)
|
||||
from docutils.languages import get_language
|
||||
|
||||
def patched_get_language(language_code, reporter=None):
|
||||
# type: (unicode, Reporter) -> Any
|
||||
return get_language(language_code)
|
||||
|
||||
@contextmanager
|
||||
def patch_docutils():
|
||||
# type: () -> Iterator[None]
|
||||
"""Patch to docutils temporarily."""
|
||||
try:
|
||||
docutils.languages.get_language = patched_get_language
|
||||
|
||||
yield
|
||||
finally:
|
||||
# restore original implementations
|
||||
docutils.languages.get_language = get_language
|
||||
|
||||
|
||||
@contextmanager
|
||||
def using_user_docutils_conf(confdir):
|
||||
# type: (unicode) -> Generator[None, None, None]
|
||||
"""Let docutils know the location of ``docutils.conf`` for Sphinx."""
|
||||
try:
|
||||
docutilsconfig = os.environ.get('DOCUTILSCONFIG', None)
|
||||
if confdir:
|
||||
os.environ['DOCUTILSCONFIG'] = path.join(path.abspath(confdir), 'docutils.conf') # type: ignore # NOQA
|
||||
|
||||
yield
|
||||
finally:
|
||||
if docutilsconfig is None:
|
||||
os.environ.pop('DOCUTILSCONFIG')
|
||||
else:
|
||||
os.environ['DOCUTILSCONFIG'] = docutilsconfig
|
||||
|
||||
|
||||
@contextmanager
|
||||
def patch_docutils(confdir=None):
|
||||
# type: (unicode) -> Generator[None, None, None]
|
||||
"""Patch to docutils temporarily."""
|
||||
with patched_get_language(), using_user_docutils_conf(confdir):
|
||||
yield
|
||||
|
||||
|
||||
class ElementLookupError(Exception):
|
||||
pass
|
||||
|
||||
@ -257,7 +282,7 @@ def directive_helper(obj, has_content=None, argument_spec=None, **option_spec):
|
||||
|
||||
@contextmanager
|
||||
def switch_source_input(state, content):
|
||||
# type: (State, ViewList) -> Generator
|
||||
# type: (State, ViewList) -> Generator[None, None, None]
|
||||
"""Switch current source input of state temporarily."""
|
||||
try:
|
||||
# remember the original ``get_source_and_line()`` method
|
||||
|
||||
@ -74,6 +74,10 @@ def copy_asset(source, destination, excluded=lambda path: False, context=None, r
|
||||
if not os.path.exists(source):
|
||||
return
|
||||
|
||||
if renderer is None:
|
||||
from sphinx.util.template import SphinxRenderer
|
||||
renderer = SphinxRenderer()
|
||||
|
||||
ensuredir(destination)
|
||||
if os.path.isfile(source):
|
||||
copy_asset_file(source, destination, context, renderer)
|
||||
|
||||
@ -17,14 +17,14 @@ from contextlib import contextmanager
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.utils import get_source_line
|
||||
from six import PY2, StringIO
|
||||
from six import PY2, StringIO, text_type
|
||||
|
||||
from sphinx.errors import SphinxWarning
|
||||
from sphinx.util.console import colorize
|
||||
|
||||
if False:
|
||||
# For type annotation
|
||||
from typing import Any, Dict, Generator, IO, List, Tuple, Union # NOQA
|
||||
from typing import Any, Dict, Generator, IO, List, Tuple, Union, Optional # NOQA
|
||||
from docutils import nodes # NOQA
|
||||
from sphinx.application import Sphinx # NOQA
|
||||
|
||||
@ -94,6 +94,36 @@ def convert_serializable(records):
|
||||
r.location = get_node_location(location) # type: ignore
|
||||
|
||||
|
||||
def get_full_module_name(node):
|
||||
# type: (nodes.Node) -> str
|
||||
"""
|
||||
return full module dotted path like: 'docutils.nodes.paragraph'
|
||||
|
||||
:param nodes.Node node: target node
|
||||
:return: full module dotted path
|
||||
"""
|
||||
return '{}.{}'.format(node.__module__, node.__class__.__name__)
|
||||
|
||||
|
||||
def repr_domxml(node, length=80):
|
||||
# type: (nodes.Node, Optional[int]) -> unicode
|
||||
"""
|
||||
return DOM XML representation of the specified node like:
|
||||
'<paragraph translatable="False"><inline classes="versionmodified">New in version...'
|
||||
|
||||
:param nodes.Node node: target node
|
||||
:param int length:
|
||||
length of return value to be striped. if false-value is specified, repr_domxml
|
||||
returns full of DOM XML representation.
|
||||
:return: DOM XML representation
|
||||
"""
|
||||
# text = node.asdom().toxml() # #4919 crush if node has secnumber with tuple value
|
||||
text = text_type(node) # workaround for #4919
|
||||
if length and len(text) > length:
|
||||
text = text[:length] + '...'
|
||||
return text
|
||||
|
||||
|
||||
class SphinxWarningLogRecord(logging.LogRecord):
|
||||
"""Log record class supporting location"""
|
||||
location = None # type: Any
|
||||
|
||||
@ -21,7 +21,7 @@ from sphinx.util import logging
|
||||
|
||||
if False:
|
||||
# For type annotation
|
||||
from typing import Any, Callable, Iterable, List, Set, Tuple, Union # NOQA
|
||||
from typing import Any, Callable, Iterable, List, Set, Tuple # NOQA
|
||||
from sphinx.builders import Builder # NOQA
|
||||
from sphinx.utils.tags import Tags # NOQA
|
||||
|
||||
@ -41,13 +41,19 @@ def apply_source_workaround(node):
|
||||
# * rawsource of term node will have: ``term text : classifier1 : classifier2``
|
||||
# * rawsource of classifier node will be None
|
||||
if isinstance(node, nodes.classifier) and not node.rawsource:
|
||||
logger.debug('[i18n] PATCH: %r to have source, line and rawsource: %s',
|
||||
logging.get_full_module_name(node), logging.repr_domxml(node))
|
||||
definition_list_item = node.parent
|
||||
node.source = definition_list_item.source
|
||||
node.line = definition_list_item.line - 1
|
||||
node.rawsource = node.astext() # set 'classifier1' (or 'classifier2')
|
||||
if isinstance(node, nodes.image) and node.source is None:
|
||||
logger.debug('[i18n] PATCH: %r to have source, line: %s',
|
||||
logging.get_full_module_name(node), logging.repr_domxml(node))
|
||||
node.source, node.line = node.parent.source, node.parent.line
|
||||
if isinstance(node, nodes.term):
|
||||
logger.debug('[i18n] PATCH: %r to have rawsource: %s',
|
||||
logging.get_full_module_name(node), logging.repr_domxml(node))
|
||||
# strip classifier from rawsource of term
|
||||
for classifier in reversed(node.parent.traverse(nodes.classifier)):
|
||||
node.rawsource = re.sub(r'\s*:\s*%s' % re.escape(classifier.astext()),
|
||||
@ -67,6 +73,8 @@ def apply_source_workaround(node):
|
||||
nodes.image, # #3093 image directive in substitution
|
||||
nodes.field_name, # #3335 field list syntax
|
||||
))):
|
||||
logger.debug('[i18n] PATCH: %r to have source and line: %s',
|
||||
logging.get_full_module_name(node), logging.repr_domxml(node))
|
||||
node.source = find_source_node(node)
|
||||
node.line = 0 # need fix docutils to get `node.line`
|
||||
return
|
||||
@ -74,7 +82,6 @@ def apply_source_workaround(node):
|
||||
|
||||
IGNORED_NODES = (
|
||||
nodes.Invisible,
|
||||
nodes.Inline,
|
||||
nodes.literal_block,
|
||||
nodes.doctest_block,
|
||||
addnodes.versionmodified,
|
||||
@ -96,17 +103,30 @@ def is_translatable(node):
|
||||
if isinstance(node, addnodes.translatable):
|
||||
return True
|
||||
|
||||
if isinstance(node, nodes.Inline) and 'translatable' not in node:
|
||||
# inline node must not be translated if 'translatable' is not set
|
||||
return False
|
||||
|
||||
if isinstance(node, nodes.TextElement):
|
||||
if not node.source:
|
||||
logger.debug('[i18n] SKIP %r because no node.source: %s',
|
||||
logging.get_full_module_name(node), logging.repr_domxml(node))
|
||||
return False # built-in message
|
||||
if isinstance(node, IGNORED_NODES) and 'translatable' not in node:
|
||||
logger.debug("[i18n] SKIP %r because node is in IGNORED_NODES "
|
||||
"and no node['translatable']: %s",
|
||||
logging.get_full_module_name(node), logging.repr_domxml(node))
|
||||
return False
|
||||
if not node.get('translatable', True):
|
||||
# not(node['translatable'] == True or node['translatable'] is None)
|
||||
logger.debug("[i18n] SKIP %r because not node['translatable']: %s",
|
||||
logging.get_full_module_name(node), logging.repr_domxml(node))
|
||||
return False
|
||||
# <field_name>orphan</field_name>
|
||||
# XXX ignore all metadata (== docinfo)
|
||||
if isinstance(node, nodes.field_name) and node.children[0] == 'orphan':
|
||||
logger.debug('[i18n] SKIP %r because orphan node: %s',
|
||||
logging.get_full_module_name(node), logging.repr_domxml(node))
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
0
tests/roots/test-html_assets/extra/index.rst
Normal file
0
tests/roots/test-html_assets/extra/index.rst
Normal file
0
tests/roots/test-html_assets/static/index.rst
Normal file
0
tests/roots/test-html_assets/static/index.rst
Normal file
@ -1089,6 +1089,10 @@ def test_enumerable_node(app, cached_etree_parse, fname, expect):
|
||||
def test_html_assets(app):
|
||||
app.builder.build_all()
|
||||
|
||||
# exclude_path and its family
|
||||
assert not (app.outdir / 'static' / 'index.html').exists()
|
||||
assert not (app.outdir / 'extra' / 'index.html').exists()
|
||||
|
||||
# html_static_path
|
||||
assert not (app.outdir / '_static' / '.htaccess').exists()
|
||||
assert not (app.outdir / '_static' / '.htpasswd').exists()
|
||||
|
||||
@ -15,6 +15,7 @@ import sys
|
||||
import pytest
|
||||
|
||||
from sphinx.testing.path import path
|
||||
from sphinx.util.docutils import patch_docutils
|
||||
|
||||
|
||||
def regex_count(expr, result):
|
||||
@ -23,7 +24,9 @@ def regex_count(expr, result):
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='docutilsconf', freshenv=True, docutilsconf='')
|
||||
def test_html_with_default_docutilsconf(app, status, warning):
|
||||
app.builder.build(['contents'])
|
||||
with patch_docutils(app.confdir):
|
||||
app.builder.build(['contents'])
|
||||
|
||||
result = (app.outdir / 'contents.html').text(encoding='utf-8')
|
||||
|
||||
assert regex_count(r'<th class="field-name">', result) == 1
|
||||
@ -39,7 +42,9 @@ def test_html_with_default_docutilsconf(app, status, warning):
|
||||
'\n')
|
||||
)
|
||||
def test_html_with_docutilsconf(app, status, warning):
|
||||
app.builder.build(['contents'])
|
||||
with patch_docutils(app.confdir):
|
||||
app.builder.build(['contents'])
|
||||
|
||||
result = (app.outdir / 'contents.html').text(encoding='utf-8')
|
||||
|
||||
assert regex_count(r'<th class="field-name">', result) == 0
|
||||
@ -50,25 +55,29 @@ def test_html_with_docutilsconf(app, status, warning):
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='docutilsconf')
|
||||
def test_html(app, status, warning):
|
||||
app.builder.build(['contents'])
|
||||
with patch_docutils(app.confdir):
|
||||
app.builder.build(['contents'])
|
||||
assert warning.getvalue() == ''
|
||||
|
||||
|
||||
@pytest.mark.sphinx('latex', testroot='docutilsconf')
|
||||
def test_latex(app, status, warning):
|
||||
app.builder.build(['contents'])
|
||||
with patch_docutils(app.confdir):
|
||||
app.builder.build(['contents'])
|
||||
assert warning.getvalue() == ''
|
||||
|
||||
|
||||
@pytest.mark.sphinx('man', testroot='docutilsconf')
|
||||
def test_man(app, status, warning):
|
||||
app.builder.build(['contents'])
|
||||
with patch_docutils(app.confdir):
|
||||
app.builder.build(['contents'])
|
||||
assert warning.getvalue() == ''
|
||||
|
||||
|
||||
@pytest.mark.sphinx('texinfo', testroot='docutilsconf')
|
||||
def test_texinfo(app, status, warning):
|
||||
app.builder.build(['contents'])
|
||||
with patch_docutils(app.confdir):
|
||||
app.builder.build(['contents'])
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='docutilsconf',
|
||||
@ -87,4 +96,5 @@ def test_docutils_source_link_with_nonascii_file(app, status, warning):
|
||||
'nonascii filename not supported on this filesystem encoding: '
|
||||
'%s', FILESYSTEMENCODING)
|
||||
|
||||
app.builder.build_all()
|
||||
with patch_docutils(app.confdir):
|
||||
app.builder.build_all()
|
||||
|
||||
@ -8,6 +8,7 @@
|
||||
:copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
|
||||
:license: BSD, see LICENSE for details.
|
||||
"""
|
||||
import os
|
||||
import pytest
|
||||
from packaging.specifiers import InvalidSpecifier
|
||||
from packaging.version import InvalidVersion
|
||||
@ -68,7 +69,7 @@ def test_reporting_with_autodoc(app, status, warning, capfd):
|
||||
written = []
|
||||
app.builder._warn_out = written.append
|
||||
app.builder.build_all()
|
||||
lines = '\n'.join(written).split('\n')
|
||||
lines = '\n'.join(written).replace(os.sep, '/').split('\n')
|
||||
failures = [l for l in lines if l.startswith('File')]
|
||||
expected = [
|
||||
'File "dir/inner.rst", line 1, in default',
|
||||
|
||||
@ -22,24 +22,26 @@ def test_graphviz_png_html(app, status, warning):
|
||||
app.builder.build_all()
|
||||
|
||||
content = (app.outdir / 'index.html').text()
|
||||
html = (r'<div class="figure" .*?>\s*<img .*?/>\s*<p class="caption">'
|
||||
html = (r'<div class="figure" .*?>\s*'
|
||||
r'<div class="graphviz"><img .*?/></div>\s*<p class="caption">'
|
||||
r'<span class="caption-text">caption of graph</span>.*</p>\s*</div>')
|
||||
assert re.search(html, content, re.S)
|
||||
|
||||
html = 'Hello <img .*?/>\n graphviz world'
|
||||
html = 'Hello <div class="graphviz"><img .*?/></div>\n graphviz world'
|
||||
assert re.search(html, content, re.S)
|
||||
|
||||
html = '<img src=".*?" alt="digraph {\n bar -> baz\n}" />'
|
||||
assert re.search(html, content, re.M)
|
||||
|
||||
html = (r'<div class="figure align-right" .*?>\s*<img .*?/>\s*<p class="caption">'
|
||||
html = (r'<div class="figure align-right" .*?>\s*'
|
||||
r'<div class="graphviz"><img .*?/></div>\s*<p class="caption">'
|
||||
r'<span class="caption-text">on right</span>.*</p>\s*</div>')
|
||||
assert re.search(html, content, re.S)
|
||||
|
||||
html = (r'<div align=\"center\" class=\"align-center\">'
|
||||
r'<img src=\".*\.png\" alt=\"digraph foo {\n'
|
||||
r'<div class="graphviz"><img src=\".*\.png\" alt=\"digraph foo {\n'
|
||||
r'centered\n'
|
||||
r'}\" />\n</div>')
|
||||
r'}\" /></div>\n</div>')
|
||||
assert re.search(html, content, re.S)
|
||||
|
||||
|
||||
@ -52,34 +54,34 @@ def test_graphviz_svg_html(app, status, warning):
|
||||
content = (app.outdir / 'index.html').text()
|
||||
|
||||
html = (r'<div class=\"figure\" .*?>\n'
|
||||
r'<object data=\".*\.svg\".*>\n'
|
||||
r'\s+<p class=\"warning\">digraph foo {\n'
|
||||
r'<div class="graphviz"><object data=\".*\.svg\".*>\n'
|
||||
r'\s*<p class=\"warning\">digraph foo {\n'
|
||||
r'bar -> baz\n'
|
||||
r'}</p></object>\n'
|
||||
r'}</p></object></div>\n'
|
||||
r'<p class=\"caption\"><span class=\"caption-text\">'
|
||||
r'caption of graph</span>.*</p>\n</div>')
|
||||
assert re.search(html, content, re.S)
|
||||
|
||||
html = (r'Hello <object.*>\n'
|
||||
r'\s+<p class=\"warning\">graph</p></object>\n'
|
||||
html = (r'Hello <div class="graphviz"><object.*>\n'
|
||||
r'\s*<p class=\"warning\">graph</p></object></div>\n'
|
||||
r' graphviz world')
|
||||
assert re.search(html, content, re.S)
|
||||
|
||||
html = (r'<div class=\"figure align-right\" .*\>\n'
|
||||
r'<object data=\".*\.svg\".*>\n'
|
||||
r'\s+<p class=\"warning\">digraph bar {\n'
|
||||
r'<div class="graphviz"><object data=\".*\.svg\".*>\n'
|
||||
r'\s*<p class=\"warning\">digraph bar {\n'
|
||||
r'foo -> bar\n'
|
||||
r'}</p></object>\n'
|
||||
r'}</p></object></div>\n'
|
||||
r'<p class=\"caption\"><span class=\"caption-text\">'
|
||||
r'on right</span>.*</p>\n'
|
||||
r'</div>')
|
||||
assert re.search(html, content, re.S)
|
||||
|
||||
html = (r'<div align=\"center\" class=\"align-center\">'
|
||||
r'<object data=\".*\.svg\".*>\n'
|
||||
r'\s+<p class=\"warning\">digraph foo {\n'
|
||||
r'<div class="graphviz"><object data=\".*\.svg\".*>\n'
|
||||
r'\s*<p class=\"warning\">digraph foo {\n'
|
||||
r'centered\n'
|
||||
r'}</p></object>\n'
|
||||
r'}</p></object></div>\n'
|
||||
r'</div>')
|
||||
assert re.search(html, content, re.S)
|
||||
|
||||
|
||||
@ -19,14 +19,34 @@ from sphinx.ext.inheritance_diagram import InheritanceException, import_classes
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='ext-inheritance_diagram')
|
||||
@pytest.mark.usefixtures('if_graphviz_found')
|
||||
def test_inheritance_diagram_html(app, status, warning):
|
||||
def test_inheritance_diagram_png_html(app, status, warning):
|
||||
app.builder.build_all()
|
||||
|
||||
content = (app.outdir / 'index.html').text()
|
||||
|
||||
pattern = ('<div class="figure" id="id1">\n'
|
||||
'<div class="graphviz">'
|
||||
'<img src="_images/inheritance-\\w+.png" alt="Inheritance diagram of test.Foo" '
|
||||
'class="inheritance"/>\n<p class="caption"><span class="caption-text">'
|
||||
'class="inheritance"/></div>\n<p class="caption"><span class="caption-text">'
|
||||
'Test Foo!</span><a class="headerlink" href="#id1" '
|
||||
'title="Permalink to this image">\xb6</a></p>')
|
||||
assert re.search(pattern, content, re.M)
|
||||
|
||||
|
||||
@pytest.mark.sphinx('html', testroot='ext-inheritance_diagram',
|
||||
confoverrides={'graphviz_output_format': 'svg'})
|
||||
@pytest.mark.usefixtures('if_graphviz_found')
|
||||
def test_inheritance_diagram_svg_html(app, status, warning):
|
||||
app.builder.build_all()
|
||||
|
||||
content = (app.outdir / 'index.html').text()
|
||||
|
||||
pattern = ('<div class="figure" id="id1">\n'
|
||||
'<div class="graphviz">'
|
||||
'<object data="_images/inheritance-\\w+.svg" '
|
||||
'type="image/svg\\+xml" class="inheritance">\n'
|
||||
'<p class=\"warning\">Inheritance diagram of test.Foo</p>'
|
||||
'</object></div>\n<p class="caption"><span class="caption-text">'
|
||||
'Test Foo!</span><a class="headerlink" href="#id1" '
|
||||
'title="Permalink to this image">\xb6</a></p>')
|
||||
assert re.search(pattern, content, re.M)
|
||||
@ -62,8 +82,9 @@ def test_inheritance_diagram_latex_alias(app, status, warning):
|
||||
content = (app.outdir / 'index.html').text()
|
||||
|
||||
pattern = ('<div class="figure" id="id1">\n'
|
||||
'<div class="graphviz">'
|
||||
'<img src="_images/inheritance-\\w+.png" alt="Inheritance diagram of test.Foo" '
|
||||
'class="inheritance"/>\n<p class="caption"><span class="caption-text">'
|
||||
'class="inheritance"/></div>\n<p class="caption"><span class="caption-text">'
|
||||
'Test Foo!</span><a class="headerlink" href="#id1" '
|
||||
'title="Permalink to this image">\xb6</a></p>')
|
||||
assert re.search(pattern, content, re.M)
|
||||
|
||||
81
tests/test_roles.py
Normal file
81
tests/test_roles.py
Normal file
@ -0,0 +1,81 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
test_roles
|
||||
~~~~~~~~~~
|
||||
|
||||
Test sphinx.roles
|
||||
|
||||
:copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
|
||||
:license: BSD, see LICENSE for details.
|
||||
"""
|
||||
|
||||
from docutils import nodes
|
||||
from mock import Mock
|
||||
|
||||
from sphinx.roles import emph_literal_role
|
||||
from sphinx.testing.util import assert_node
|
||||
|
||||
|
||||
def test_samp():
|
||||
# normal case
|
||||
text = 'print 1+{variable}'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, ("print 1+",
|
||||
[nodes.emphasis, "variable"])],))
|
||||
assert msg == []
|
||||
|
||||
# two emphasis items
|
||||
text = 'print {1}+{variable}'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, ("print ",
|
||||
[nodes.emphasis, "1"],
|
||||
"+",
|
||||
[nodes.emphasis, "variable"])],))
|
||||
assert msg == []
|
||||
|
||||
# empty curly brace
|
||||
text = 'print 1+{}'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, "print 1+{}"],))
|
||||
assert msg == []
|
||||
|
||||
# half-opened variable
|
||||
text = 'print 1+{variable'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, "print 1+{variable"],))
|
||||
assert msg == []
|
||||
|
||||
# nested
|
||||
text = 'print 1+{{variable}}'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, ("print 1+",
|
||||
[nodes.emphasis, "{variable"],
|
||||
"}")],))
|
||||
assert msg == []
|
||||
|
||||
# emphasized item only
|
||||
text = '{variable}'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, nodes.emphasis, "variable"],))
|
||||
assert msg == []
|
||||
|
||||
# escaping
|
||||
text = r'print 1+\{variable}'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, "print 1+{variable}"],))
|
||||
assert msg == []
|
||||
|
||||
# escaping (2)
|
||||
text = r'print 1+\{{variable}\}'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, ("print 1+{",
|
||||
[nodes.emphasis, "variable"],
|
||||
"}")],))
|
||||
assert msg == []
|
||||
|
||||
# escape a backslash
|
||||
text = r'print 1+\\{variable}'
|
||||
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
|
||||
assert_node(ret, ([nodes.literal, ("print 1+\\",
|
||||
[nodes.emphasis, "variable"])],))
|
||||
assert msg == []
|
||||
Loading…
Reference in New Issue
Block a user