Merge branch 'master' into 4818_warnings_on_including

AUTHORS

@@ -40,6 +40,7 @@ Other contributors, listed alphabetically, are:
 * Timotheus Kampik - JS theme & search enhancements
 * Dave Kuhlman -- original LaTeX writer
 * Blaise Laflamme -- pyramid theme
+* Chris Lamb -- reproducibility fixes
 * Thomas Lamb -- linkcheck builder
 * Łukasz Langa -- partial support for autodoc
 * Ian Lee -- quickstart improvements

CHANGES

@@ -35,6 +35,7 @@ Deprecated
 * #2157: helper function ``warn()`` for HTML themes is deprecated
 * ``env._nitpick_ignore`` is deprecated
 * ``app.override_domain()`` is deprecated
+* ``app.add_stylesheet()`` is deprecated
 
 For more details, see `deprecation APIs list
 <http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_
@@ -58,6 +59,9 @@ Features added
 * LaTeX: new key ``'fvset'`` for :confval:`latex_elements`. For
   XeLaTeX/LuaLaTeX its default sets ``fanvyvrb`` to use normal, not small,
   fontsize in code-blocks (refs: #4793)
+* Add :confval:`html_css_files` and :confval:`epub_css_files` for adding CSS
+  files from configuration
+* #4834: Ensure set object descriptions are reproducible.
 * Improve warning messages during including (refs: #4818)
 
 Bugs fixed
@@ -97,6 +101,13 @@ Bugs fixed
 * #4789: imgconverter: confused by convert.exe of Windows
 * #4783: On windows, Sphinx crashed when drives of srcdir and outdir are
   different
+* #4812: autodoc ignores type annotated variables
+* #4817: wrong URLs on warning messages
+* #4784: latex: :confval:`latex_show_urls` assigns incorrect footnote numbers if
+  hyperlinks exists inside substitutions
+* #4837: latex with class memoir Error: Font command ``\sf`` is not supported
+* #4803: latex: too slow in proportion to number of auto numbered footnotes
+* #4838: htmlhelp: The entries in .hhp file is not ordered
 
 Testing
 --------
@@ -131,6 +142,7 @@ Bugs fixed
 * #1435: qthelp builder should htmlescape keywords
 * epub: Fix docTitle elements of toc.ncx is not escaped
 * #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
+* #4767: html: search highlighting breaks mathjax equations
 
 Release 1.7.1 (released Feb 23, 2018)
 =====================================

EXAMPLES

@@ -317,7 +317,7 @@ Documentation using a custom theme or integrated in a website
 * PSI4: http://www.psicode.org/psi4manual/master/index.html
 * PyMOTW: https://pymotw.com/2/
 * python-aspectlib: https://python-aspectlib.readthedocs.io/
-  (`sphinx_py3doc_enhanced_theme <https://pypi.python.org/pypi/sphinx_py3doc_enhanced_theme>`__)
+  (`sphinx_py3doc_enhanced_theme <https://pypi.org/project/sphinx_py3doc_enhanced_theme/>`__)
 * QGIS: https://qgis.org/en/docs/index.html
 * qooxdoo: http://www.qooxdoo.org/current/
 * Roundup: http://www.roundup-tracker.org/

README.rst

@@ -3,7 +3,7 @@
 ========
 
 .. image:: https://img.shields.io/pypi/v/sphinx.svg
-   :target: https://pypi.python.org/pypi/Sphinx
+   :target: https://pypi.org/project/Sphinx/
    :alt: Package on PyPi
 
 .. image:: https://readthedocs.org/projects/sphinx/badge/
@@ -71,7 +71,7 @@ We also publish beta releases::
 If you wish to install `Sphinx` for development purposes, refer to `the
 contributors guide`__.
 
-__ https://pypi.python.org/pypi/Sphinx
+__ https://pypi.org/project/Sphinx/
 __ http://www.sphinx-doc.org/en/master/devguide.html
 
 Documentation

doc/_templates/indexsidebar.html

@@ -8,11 +8,11 @@ <h3>Download</h3>
   not released yet.{%endtrans%}</p>
 <p>{%trans%}You can use it from the
   <a href="https://github.com/sphinx-doc/sphinx/">Git repo</a> or look for
-  released versions in the <a href="https://pypi.python.org/pypi/Sphinx">Python
+  released versions in the <a href="https://pypi.org/project/Sphinx/">Python
     Package Index</a>.{%endtrans%}</p>
 {% else %}
 <p>{%trans%}Current version: <b><a href="changes.html">{{ version }}</a></b>{%endtrans%}</p>
-<p>{%trans%}Get Sphinx from the <a href="https://pypi.python.org/pypi/Sphinx">Python Package
+<p>{%trans%}Get Sphinx from the <a href="https://pypi.org/project/Sphinx/">Python Package
 Index</a>, or install it with:{%endtrans%}</p>
 <pre>pip install -U Sphinx</pre>
 {% endif %}

doc/_themes/sphinx13/layout.html

@@ -70,7 +70,7 @@
 <div class="pageheader">
   <ul>
     <li><a href="{{ pathto('index') }}">Home</a></li>
-    <li><a href="{{ pathto('install') }}">Get it</a></li>
+    <li><a href="{{ pathto('usage/installation') }}">Get it</a></li>
     <li><a href="{{ pathto('contents') }}">Docs</a></li>
     <li><a href="{{ pathto('develop') }}">Extend/Develop</a></li>
   </ul>

doc/builders.rst

@@ -288,7 +288,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
             globalcontext_filename = 'globalcontext.phpdump'
             searchindex_filename = 'searchindex.phpdump'
 
-   .. _PHP serialization: https://pypi.python.org/pypi/phpserialize
+   .. _PHP serialization: https://pypi.org/project/phpserialize/
 
    .. attribute:: implementation
 

doc/conf.py

@@ -39,7 +39,7 @@
 epub_scheme = 'url'
 epub_identifier = epub_publisher
 epub_pre_files = [('index.xhtml', 'Welcome')]
-epub_post_files = [('install.xhtml', 'Installing Sphinx'),
+epub_post_files = [('usage/installation.xhtml', 'Installing Sphinx'),
                    ('develop.xhtml', 'Sphinx development')]
 epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
                       '_static/jquery.js', '_static/searchtools.js',

doc/config.rst

@@ -59,9 +59,6 @@ Important points to note:
   Note that the current builder tag is not available in ``conf.py``, as it is
   created *after* the builder is initialized.
 
-.. seealso:: Additional configurations, such as adding stylesheets,
-   javascripts, builders, etc. can be made through the :doc:`/extdev/appapi`.
-
 
 General configuration
 ---------------------
@@ -195,8 +192,9 @@ General configuration
    .. index:: pair: global; substitutions
 
    A string of reStructuredText that will be included at the end of every source
-   file that is read.  This is the right place to add substitutions that should
-   be available in every file.  An example::
+   file that is read.  This is a possible place to add substitutions that should
+   be available in every file (another being :confval:`rst_prolog`).  An
+   example::
 
       rst_epilog = """
       .. |psf| replace:: Python Software Foundation
@@ -206,8 +204,16 @@ General configuration
 
 .. confval:: rst_prolog
 
+   .. index:: pair: global; substitutions
+
    A string of reStructuredText that will be included at the beginning of every
-   source file that is read.
+   source file that is read.  This is a possible place to add substitutions that
+   should be available in every file (another being :confval:`rst_epilog`).  An
+   example::
+
+      rst_prolog = """
+      .. |psf| replace:: Python Software Foundation
+      """
 
    .. versionadded:: 1.0
 
@@ -846,6 +852,22 @@ that use Sphinx's HTMLWriter class.
       The image file will be copied to the ``_static`` directory of the output
       HTML, but only if the file does not already exist there.
 
+.. confval:: html_css_files
+
+   A list of CSS files.  The entry must be a *filename* string or a tuple
+   containing the *filename* string and the *attributes* dictionary.  The
+   *filename* must be relative to the :confval:`html_static_path`, or a full URI
+   with scheme like ``http://example.org/style.css``.  The *attributes* is used
+   for attributes of ``<link>`` tag.  It defaults to an empty list.
+
+   Example::
+
+       html_css_files = ['custom.css'
+                         'https://example.com/css/custom.css',
+                         ('print.css', {'media': 'print'})]
+
+   .. versionadded:: 1.8
+
 .. confval:: html_static_path
 
    A list of paths that contain custom static files (such as style
@@ -1125,8 +1147,8 @@ that use Sphinx's HTMLWriter class.
       Sphinx uses a Python implementation by default.  You can use a C
       implementation to accelerate building the index file.
 
-      * `PorterStemmer <https://pypi.python.org/pypi/PorterStemmer>`_ (``en``)
-      * `PyStemmer <https://pypi.python.org/pypi/PyStemmer>`_ (all languages)
+      * `PorterStemmer <https://pypi.org/project/PorterStemmer/>`_ (``en``)
+      * `PyStemmer <https://pypi.org/project/PyStemmer/>`_ (all languages)
 
    .. versionadded:: 1.1
       With support for ``en`` and ``ja``.
@@ -1158,7 +1180,7 @@ that use Sphinx's HTMLWriter class.
          library ('libmecab.so' for linux, 'libmecab.dll' for windows) is required.
       :'sphinx.search.ja.JanomeSplitter':
          Janome binding. To use this splitter,
-         `Janome <https://pypi.python.org/pypi/Janome>`_ is required.
+         `Janome <https://pypi.org/project/Janome/>`_ is required.
 
       To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are also
       acceptable. However it will be deprecated in Sphinx-1.6.
@@ -1511,6 +1533,14 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 
    .. versionadded:: 1.1
 
+.. confval:: epub_css_files
+
+   A list of CSS files.  The entry must be a *filename* string or a tuple
+   containing the *filename* string and the *attributes* dictionary.  For more
+   information, see :confval:`html_css_files`.
+
+   .. versionadded:: 1.8
+
 .. confval:: epub_guide
 
    Meta data for the guide element of :file:`content.opf`. This is a

doc/develop.rst

@@ -141,5 +141,5 @@ own extensions.
 .. _inlinesyntaxhighlight: https://sphinxcontrib-inlinesyntaxhighlight.readthedocs.io/
 .. _CMake: https://cmake.org
 .. _domaintools: https://bitbucket.org/klorenz/sphinxcontrib-domaintools
-.. _restbuilder: https://pypi.python.org/pypi/sphinxcontrib-restbuilder
+.. _restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
 .. _Lasso: http://www.lassosoft.com/

doc/extdev/index.rst

@@ -114,6 +114,11 @@ The following is a list of deprecated interface.
      - (will be) Removed
      - Alternatives
 
+   * - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+     - 1.8
+     - 4.0
+     - :meth:`~sphinx.application.Sphinx.add_css_file()`
+
    * - ``sphinx.application.Sphinx.override_domain()``
      - 1.8
      - 3.0
@@ -263,7 +268,7 @@ The following is a list of deprecated interface.
    * - ``sphinx.websupport``
      - 1.6
      - 2.0
-     - `sphinxcontrib-websupport <https://pypi.python.org/pypi/sphinxcontrib-websupport>`_
+     - `sphinxcontrib-websupport <https://pypi.org/project/sphinxcontrib-websupport/>`_
 
    * - ``StandaloneHTMLBuilder.css_files``
      - 1.6

doc/faq.rst

@@ -23,7 +23,7 @@ How do I...
    Use themes, see :doc:`theming`.
 
 ... add global substitutions or includes?
-   Add them in the :confval:`rst_epilog` config value.
+   Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value.
 
 ... display the whole TOC tree in the sidebar?
    Use the :data:`toctree` callable in a custom layout template, probably in the
@@ -72,7 +72,7 @@ SCons
 
 PyPI
    Jannis Leidel wrote a `setuptools command
-   <https://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically
+   <https://pypi.org/project/Sphinx-PyPI-upload/>`_ that automatically
    uploads Sphinx documentation to the PyPI package documentation area at
    https://pythonhosted.org/.
 

doc/intl.rst

@@ -322,8 +322,8 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
 .. [2] Because nobody expects the Spanish Inquisition!
 
 
-.. _`transifex-client`: https://pypi.python.org/pypi/transifex-client
-.. _`sphinx-intl`: https://pypi.python.org/pypi/sphinx-intl
+.. _`transifex-client`: https://pypi.org/project/transifex-client/
+.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
 .. _Transifex: https://www.transifex.com/
 .. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/
 .. _`Transifex Client documentation`: http://docs.transifex.com/developer/client/

doc/intro.rst

@@ -29,7 +29,7 @@ This section is intended to collect helpful hints for those wanting to migrate
 to reStructuredText/Sphinx from other documentation systems.
 
 * Gerard Flanagan has written a script to convert pure HTML to reST; it can be
-  found at the `Python Package Index <https://pypi.python.org/pypi/html2rest>`_.
+  found at the `Python Package Index <https://pypi.org/project/html2rest/>`_.
 
 * For converting the old Python docs to Sphinx, a converter was written which
   can be found at `the Python SVN repository
@@ -40,7 +40,7 @@ to reStructuredText/Sphinx from other documentation systems.
   markup; it is at `GitHub <https://github.com/wojdyr/db2rst>`_.
 
 * Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents
-  to Sphinx: `odt2sphinx <https://pypi.python.org/pypi/odt2sphinx/>`_.
+  to Sphinx: `odt2sphinx <https://pypi.org/project/odt2sphinx/>`_.
 
 * To convert different markups, `Pandoc <https://pandoc.org/>`_ is
   a very helpful tool.

doc/man/sphinx-apidoc.rst

@@ -15,8 +15,10 @@ style of other automatic API documentation tools.
 
 *MODULE_PATH* is the path to a Python package to document, and *OUTPUT_PATH* is
 the directory where the generated sources are placed. Any *EXCLUDE_PATTERN*\s
-given are `fnmatch-style <fnmatch>`_ file and/or directory patterns that will
-be excluded from generation.
+given are `fnmatch-style`_ file and/or directory patterns that will be excluded
+from generation.
+
+.. _fnmatch-style: https://docs.python.org/3/library/fnmatch.html
 
 .. warning::
 

doc/theming.rst

@@ -134,7 +134,7 @@ These themes are:
   Check out at its `installation page`_ how to set up properly
   :confval:`html_sidebars` for its use.
 
-  .. _Alabaster theme: https://pypi.python.org/pypi/alabaster
+  .. _Alabaster theme: https://pypi.org/project/alabaster/
   .. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
 
 * **classic** -- This is the classic theme, which looks like `the Python 2
@@ -418,7 +418,7 @@ Third Party Themes
   View a working demo over on readthedocs.org. You can get install and options
   information at `Read the Docs Sphinx Theme`_ page.
 
-  .. _Read the Docs Sphinx Theme: https://pypi.python.org/pypi/sphinx_rtd_theme
+  .. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/
 
   .. versionchanged:: 1.4
      **sphinx_rtd_theme** has become optional.

doc/usage/installation.rst

@@ -132,7 +132,7 @@ Installation from PyPI
 ----------------------
 
 Sphinx packages are published on the `Python Package Index
-<https://pypi.python.org/pypi/Sphinx>`_.  The preferred tool for installing
+<https://pypi.org/project/Sphinx/>`_.  The preferred tool for installing
 packages from *PyPI* is :command:`pip`.  This tool is provided with all modern
 versions of Python.
 

doc/usage/restructuredtext/basics.rst

@@ -508,11 +508,14 @@ or this::
 See the :duref:`reST reference for substitutions <substitution-definitions>`
 for details.
 
+.. index:: ! pair: global; substitutions
+
 If you want to use some substitutions for all documents, put them into
-:confval:`rst_prolog` or put them into a separate file and include it into all
-documents you want to use them in, using the :rst:dir:`include` directive.  (Be
-sure to give the include file a file name extension differing from that of
-other source files, to avoid Sphinx finding it as a standalone document.)
+:confval:`rst_prolog` or :confval:`rst_epilog` or put them into a separate file
+and include it into all documents you want to use them in, using the
+:rst:dir:`include` directive.  (Be sure to give the include file a file name
+extension differing from that of other source files, to avoid Sphinx finding it
+as a standalone document.)
 
 Sphinx defines some default substitutions, see :ref:`default-substitutions`.
 

doc/usage/restructuredtext/directives.rst

@@ -596,7 +596,8 @@ __ http://pygments.org/docs/lexers/
    ``start-after`` is given as a string option, only lines that follow the
    first line containing that string are included.  If ``end-before`` is given
    as a string option, only lines that precede the first lines containing that
-   string are included.
+   string are included. The ``start-at`` and ``end-at`` options behave in a
+   similar way, but the lines containing the matched string are included.
 
    With lines selected using ``start-after`` it is still possible to use
    ``lines``, the first allowed line having by convention the line number
@@ -638,6 +639,9 @@ __ http://pygments.org/docs/lexers/
       Added the ``diff``, ``lineno-match``, ``caption``, ``name``, and
       ``dedent`` options.
 
+   .. versionchanged:: 1.5
+      Added the ``start-at``, and ``end-at`` options.
+
    .. versionchanged:: 1.6
       With both ``start-after`` and ``lines`` in use, the first line as per
       ``start-after`` is considered to be with line number ``1`` for ``lines``.