Merge branch 'master' into refactor_latex_footnotes

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
 --------
 

README.rst

@@ -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
 

doc/contents.rst

@@ -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

doc/extdev/index.rst

@@ -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

doc/latex.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: python
+.. highlight:: python
 
 .. _latex:
 

doc/markdown.rst

@@ -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>`__.

doc/theming.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: python
+.. highlight:: python
 
 HTML theming support
 ====================

doc/usage/configuration.rst

@@ -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
+* Remember that document names use ``/`` as the path separator and don't
-  the file name extension.
+  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
+   The configuration file itself can be an extension; for that, you only need
-   provide a :func:`setup` function in it.
+   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
+   A list of glob-style patterns that should be excluded when looking for
-   files. [1]_ They are matched against the source file names relative to the
+   source files. [1]_ They are matched against the source file names relative
-   source directory, using slashes as directory separators on all platforms.
+   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
+   A string with the fully-qualified name of a callable (or simply a class)
-   returns an instance of :class:`~sphinx.application.TemplateBridge`.  This
+   that returns an instance of :class:`~sphinx.application.TemplateBridge`.
-   instance is then used to render HTML documents, and possibly the output of
+   This instance is then used to render HTML documents, and possibly the output
-   other builders (currently the changes builder).  (Note that the template
+   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.
+   If true, keep warnings as "system message" paragraphs in the built
-   Regardless of this setting, warnings are always written to the standard error
+   documents.  Regardless of this setting, warnings are always written to the
-   stream when ``sphinx-build`` is run.
+   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
+   compare it with its version and refuse to build if it is too old.  Default
-   no requirement.
+   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
+   This value can be a dictionary specifying version requirements for
-   in :confval:`extensions`, e.g. ``needs_extensions =
+   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
+   A list of ``(type, target)`` tuples (by default empty) that should be
-   when generating warnings in "nitpicky mode".  Note that ``type`` should
+   ignored when generating warnings in "nitpicky mode".  Note that ``type``
-   include the domain name if present.  Example entries would be ``('py:func',
+   should include the domain name if present.  Example entries would be
-   'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``.
+   ``('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
+      The LaTeX builder always assigns numbers whether this option is enabled
-      not.
+      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
+   Trim spaces before footnote references that are necessary for the reST
-   to recognize the footnote, but do not look too nice in the output.
+   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
+   The style sheet to use for HTML pages.  A file of that name must exist
-   in Sphinx's :file:`static/` path, or in one of the custom paths given in
+   either in Sphinx's :file:`static/` path, or in one of the custom paths given
-   :confval:`html_static_path`.  Default is the stylesheet given by the selected
+   in :confval:`html_static_path`.  Default is the stylesheet given by the
-   theme.  If you only want to add or override a few things compared to the
+   selected theme.  If you only want to add or override a few things compared
-   theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet.
+   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
+   A shorter "title" for the HTML docs.  This is used in for links in the
-   and in the HTML Help docs.  If not given, it defaults to the value of
+   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
+   As these files are not meant to be built, they are automatically excluded
-   :confval:`exclude_patterns`.
+   from source files.
 
    .. versionadded:: 1.2
 
    .. versionchanged:: 1.4
-      The dotfiles in the extra directory will be copied to the output directory.
+      The dotfiles in the extra directory will be copied to the output
-      And it refers :confval:`exclude_patterns` on copying extra files and
+      directory.  And it refers :confval:`exclude_patterns` on copying extra
-      directories, and ignores if path matches to patterns.
+      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
+   If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ description
-   output, and all pages will contain a ``<link>`` tag referring to it.  Since
+   file will be output, and all pages will contain a ``<link>`` tag referring
-   OpenSearch doesn't support relative URLs for its search page location, the
+   to it.  Since OpenSearch doesn't support relative URLs for its search page
-   value of this option must be the base URL from which these documents are
+   location, the value of this option must be the base URL from which these
-   served (without trailing slash), e.g. ``"https://docs.python.org"``.  The
+   documents are served (without trailing slash), e.g.
-   default is ``''``.
+   ``"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
+      _`type` is dotted module path string to specify Splitter implementation
-      should be derived from :class:`sphinx.search.ja.BaseSplitter`.
+      which should be derived from :class:`sphinx.search.ja.BaseSplitter`.  If
-      If not specified or None is specified, ``'sphinx.search.ja.DefaultSplitter'`` will
+      not specified or None is specified,
-      be used.
+      ``'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
+         MeCab binding. To use this splitter, 'mecab' python binding or dynamic
-         library ('libmecab.so' for linux, 'libmecab.dll' for windows) is required.
+         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
+         _`lib option` is the library name for finding the MeCab library via
-         the Python binding is not installed.
+         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_enc option` is the encoding for the user dictionary file
-         ``user_dic`` option. Default is 'utf8'.
+         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
+      html_search_options for Japanese is re-organized and any custom splitter
-      used by `type`_ settings.
+      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
+   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
+   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
+   output is usually not wise.  This defaults to ``'epub'``, a theme designed
-   save visual space.
+   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
+   The publisher of the document.  This is put in the Dublin Core metadata.
-   may use any sensible string, e.g. the project homepage.  The defaults to the
+   You may use any sensible string, e.g. the project homepage.  The defaults to
-   :confval:`author` option.
+   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.
+   `XML's Name format <https://www.w3.org/TR/REC-xml/#NT-NameStartChar>`_
-   You can't use hyphen, period, numbers as a first character.
+   string.  You can't use hyphen, period, numbers as a first character.  The
-   The default value is ``'unknown'``.
+   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``,
+        used in the specification); for ``72px=1in``, simply use ``'1bp'``; for
-        simply use ``'1bp'``; for ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
+        ``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
+        if you want to generate a differently-styled title page.
-        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
+   A list of file names, relative to the configuration directory, to copy to
-   build directory when building LaTeX output.  This is useful to copy files
+   the build directory when building LaTeX output.  This is useful to copy
-   that Sphinx doesn't copy automatically, e.g. if they are referenced in custom
+   files that Sphinx doesn't copy automatically, e.g. if they are referenced in
-   LaTeX added in ``latex_elements``.  Image files that are referenced in source
+   custom LaTeX added in ``latex_elements``.  Image files that are referenced
-   files (e.g. via ``.. image::``) are copied automatically.
+   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
+   You have to make sure yourself that the filenames don't collide with those
-   any automatically copied files.
+   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 ``" "``
+   Suffix for section numbers in text output.  Default: ``". "``. Set to
-   to suppress the final dot on section numbers.
+   ``" "`` 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
+   *startdocname*
-     documents referenced by it in TOC trees will be included in the manual file
+     Document name that is the "root" of the manual page.  All documents
-     too.  (If you want one master manual page, use your :confval:`master_doc`
+     referenced by it in TOC trees will be included in the manual file too.
-     here.)
+     (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
+   *name*
-     well as the name of the manual page (in the NAME section).
+     Name of the manual page.  This should be a short string without spaces or
-   * *description*: description of the manual page.  This is used in the NAME
+     special characters.  It is used to determine the file name as well as the
-     section.
+     name of the manual page (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
+   *description*
-     AUTHORS section in the manual page.
+     Description of the manual page.  This is used in the NAME section.
-   * *section*: The manual page section.  Used for the output file name as well
+
-     as in the manual page header.
+   *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
+   *startdocname*
-     documents referenced by it in TOC trees will be included in the Texinfo
+     Document name that is the "root" of the Texinfo file.  All documents
-     file too.  (If you want only one Texinfo file, use your
+     referenced by it in TOC trees will be included in the Texinfo file too.
-     :confval:`master_doc` here.)
+     (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.
+   *targetname*
-   * *title*: Texinfo document title.  Can be empty to use the title of the
+     File name (no extension) of the Texinfo file in the output directory.
-     *startdoc*.  Inserted as Texinfo markup, so special characters like @ and
+
-     {} will need to be escaped to be inserted literally.
+   *title*
-   * *author*: Author for the Texinfo document.  Inserted as Texinfo markup.
+     Texinfo document title.  Can be empty to use the title of the *startdoc*.
-     Use ``@*`` to separate multiple authors, as in: ``'John@*Sarah'``.
+     Inserted as Texinfo markup, so special characters like ``@`` and ``{}``
-   * *dir_entry*: The name that will appear in the top-level ``DIR`` menu file.
+     will need to be escaped to be inserted literally.
-   * *description*: Descriptive text to appear in the top-level ``DIR`` menu
+
-     file.
+   *author*
-   * *category*: Specifies the section which this entry will appear in the
+     Author for the Texinfo document.  Inserted as Texinfo markup.  Use ``@*``
-     top-level ``DIR`` menu file.
+     to separate multiple authors, as in: ``'John@*Sarah'``.
-   * *toctree_only*: Must be ``True`` or ``False``.  If true, the *startdoc*
+
-     document itself is not included in the output, only the documents
+   *dir_entry*
-     referenced by it via TOC trees.  With this option, you can put extra stuff
+     The name that will appear in the top-level ``DIR`` menu file.
-     in the master document that shows up in the HTML, but not the Texinfo
+
-     output.
+   *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
+       these all don't match slashes.  A double star ``**`` can be used to
-       any sequence of characters *including* slashes.
+       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.
+   A list of prefixes that will be ignored when sorting C++ objects in the
-   For example ``['awesome_lib::']``.
+   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.
+   A list of strings that the parser additionally should accept as attributes
-   That is, if ``my_align_as`` is in the list, then ``my_align_as(X)`` is parsed as an attribute
+   with one argument.  That is, if ``my_align_as`` is in the list, then
-   for all strings ``X`` that have balanced brances (``()``, ``[]``, and ``{}``).
+   ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have
-   This can for example be used when attributes have been ``#define`` d for portability.
+   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

doc/usage/markdown.rst

@@ -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

doc/usage/quickstart.rst

@@ -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

doc/usage/restructuredtext/basics.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: rst
+.. highlight:: rst
 
 .. _rst-primer:
 

doc/usage/restructuredtext/field-lists.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: rst
+.. highlight:: rst
 
 ===========
 Field Lists

doc/usage/restructuredtext/roles.rst

@@ -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:

setup.cfg

@@ -51,6 +51,7 @@ follow_imports = skip
 incremental = True
 check_untyped_defs = True
 warn_unused_ignores = True
+strict_optional = False
 
 [tool:pytest]
 filterwarnings =

sphinx/builders/__init__.py

@@ -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__']:

sphinx/builders/html.py

@@ -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]

sphinx/builders/qthelp.py

@@ -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

sphinx/cmd/build.py

@@ -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,

sphinx/directives/code.py

@@ -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)

sphinx/environment/__init__.py

@@ -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 import logging
-from sphinx.util.docutils import sphinx_domains, WarningStream
+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]

sphinx/ext/graphviz.py

@@ -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">
+            self.body.append('<div class="graphviz">')
-            <p class="warning">%s</p></object>\n''' % (fname, alt)
+            self.body.append('<object data="%s" type="image/svg+xml" %s>\n' %
-            self.body.append(svgtag)
+                             (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')
 

sphinx/ext/inheritance_diagram.py

@@ -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 = {

sphinx/roles.py

@@ -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
+    parts = list(parens_re.split(utils.unescape(text)))
-        if m.start() > pos:
+    stack = ['']
-            txt = text[pos:m.start()]
+    for part in parts:
-            retnode += nodes.Text(txt, txt)
+        matched = parens_re.match(part)
-        retnode += nodes.emphasis(m.group(1), m.group(1))
+        if matched:
-        pos = m.end()
+            backslashes = len(part) - 1
-    if pos < len(text):
+            if backslashes % 2 == 1:    # escaped
-        retnode += nodes.Text(text[pos:], text[pos:])
+                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], []
 
 

sphinx/search/da.py

@@ -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())

sphinx/search/es.py

@@ -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())

sphinx/search/fi.py

@@ -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())

sphinx/search/hu.py

@@ -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())

sphinx/search/it.py

@@ -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())

sphinx/search/nl.py

@@ -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())

sphinx/search/no.py

@@ -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())

sphinx/search/pt.py

@@ -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())

sphinx/search/ro.py

@@ -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())

sphinx/search/ru.py

@@ -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())

sphinx/search/sv.py

@@ -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())

sphinx/search/tr.py

@@ -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())

sphinx/search/zh.py

@@ -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())

sphinx/setup_command.py

@@ -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,

sphinx/util/docutils.py

@@ -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):
+@contextmanager
-    # type: (unicode, Reporter) -> Any
+def patched_get_language():
-    """A wrapper for docutils.languages.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
     """
+    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

sphinx/util/fileutil.py

@@ -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)

sphinx/util/logging.py

@@ -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

sphinx/util/nodes.py

@@ -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
 

tests/test_build_html.py

@@ -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()

tests/test_docutilsconf.py

@@ -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):
+    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):
+    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,24 +55,28 @@ def test_html_with_docutilsconf(app, status, warning):
 
 @pytest.mark.sphinx('html', testroot='docutilsconf')
 def test_html(app, status, warning):
+    with patch_docutils(app.confdir):
         app.builder.build(['contents'])
     assert warning.getvalue() == ''
 
 
 @pytest.mark.sphinx('latex', testroot='docutilsconf')
 def test_latex(app, status, warning):
+    with patch_docutils(app.confdir):
         app.builder.build(['contents'])
     assert warning.getvalue() == ''
 
 
 @pytest.mark.sphinx('man', testroot='docutilsconf')
 def test_man(app, status, warning):
+    with patch_docutils(app.confdir):
         app.builder.build(['contents'])
     assert warning.getvalue() == ''
 
 
 @pytest.mark.sphinx('texinfo', testroot='docutilsconf')
 def test_texinfo(app, status, warning):
+    with patch_docutils(app.confdir):
         app.builder.build(['contents'])
 
 
@@ -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)
 
+    with patch_docutils(app.confdir):
         app.builder.build_all()

tests/test_ext_doctest.py

@@ -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',

tests/test_ext_graphviz.py

@@ -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 -&gt; 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'<div class="graphviz"><object data=\".*\.svg\".*>\n'
-            r'\s+<p class=\"warning\">digraph foo {\n'
+            r'\s*<p class=\"warning\">digraph foo {\n'
             r'bar -&gt; 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'
+    html = (r'Hello <div class="graphviz"><object.*>\n'
-            r'\s+<p class=\"warning\">graph</p></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'<div class="graphviz"><object data=\".*\.svg\".*>\n'
-            r'\s+<p class=\"warning\">digraph bar {\n'
+            r'\s*<p class=\"warning\">digraph bar {\n'
             r'foo -&gt; 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'<div class="graphviz"><object data=\".*\.svg\".*>\n'
-            r'\s+<p class=\"warning\">digraph foo {\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)
 

tests/test_ext_inheritance_diagram.py

@@ -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)

tests/test_roles.py

@@ -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 == []