Merge branch 'master' into 3638_eqref_format

doc/_static/conf.py.txt

@@ -167,11 +167,6 @@ html_static_path = ['_static']
 #
 # html_last_updated_fmt = None
 
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#
-# html_use_smartypants = True
-
 # Custom sidebar templates, maps document names to template names.
 #
 # html_sidebars = {}
@@ -280,12 +275,6 @@ latex_documents = [
 #
 # latex_appendices = []
 
-# If false, will not define \strong, \code, \titleref, \crossref ... but only
-# \sphinxstrong, ..., \sphinxtitleref, ... to help avoid clash with user added
-# packages.
-#
-# latex_keep_old_macro_names = True
-
 # If false, no module index is generated.
 #
 # latex_domain_indices = True

doc/_templates/indexsidebar.html

@@ -3,7 +3,7 @@
   {%trans%}project{%endtrans%}</p>
 
 <h3>Download</h3>
-{% if version.endswith('a0') %}
+{% if version.endswith('+') %}
 <p>{%trans%}This documentation is for version <b><a href="changes.html">{{ version }}</a></b>, which is
   not released yet.{%endtrans%}</p>
 <p>{%trans%}You can use it from the

doc/builders.rst

@@ -125,26 +125,6 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: supported_image_types
 
-.. module:: sphinx.builders.epub2
-.. class:: Epub2Builder
-
-   This builder produces the same output as the standalone HTML builder, but
-   also generates an *epub* file for ebook readers.  See :ref:`epub-faq` for
-   details about it.  For definition of the epub format, have a look at
-   `<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_.
-   The builder creates *EPUB 2* files.
-
-   .. autoattribute:: name
-
-   .. autoattribute:: format
-
-   .. autoattribute:: supported_image_types
-
-   .. deprecated:: 1.5
-
-      Since Sphinx-1.5, the epub3 builder is used for the default builder of epub.
-      Now EpubBuilder is renamed to epub2.
-
 .. module:: sphinx.builders.epub3
 .. class:: Epub3Builder
 
@@ -202,6 +182,31 @@ The builder's "name" must be given to the **-b** command-line option of
       .. versionchanged:: 1.6
          Use of ``latexmk`` on GNU/Linux or Mac OS X.
 
+      Since 1.6, ``make latexpdf`` (or ``make -C "<builddir>/latex"`` after a
+      ``sphinx-build`` run) uses ``latexmk`` (on GNU/Linux and Mac OS X).
+      It invokes it with option ``-f`` which attempts to complete targets
+      even in case of LaTeX processing errors. This can be overridden via
+      ``LATEXMKOPTS`` variable, for example:
+
+      .. code-block:: console
+
+         make latexpdf LATEXMKOPTS=""
+
+      The ``pdflatex`` calls themselves obey the ``LATEXOPTS`` variable whose
+      default is ``--interaction=nonstopmode`` (same as ``-interaction
+      nonstopmode``.) In order to stop the
+      compilation on first error one can use ``--halt-on-error``.
+
+      Example:
+
+      .. code-block:: console
+
+         make latexpdf LATEXMKOPTS="-silent" LATEXOPTS="--halt-on-error"
+
+      In case the first ``pdflatex`` run aborts with an error, this will stop
+      further ``latexmk`` processing (no ``-f`` option). The console output
+      will be kept to a bare minimum during target processing (``-silent``).
+
    .. autoattribute:: name
 
    .. autoattribute:: format

doc/conf.py

@@ -16,7 +16,7 @@ exclude_patterns = ['_build']
 
 project = 'Sphinx'
 copyright = '2007-2017, Georg Brandl and the Sphinx team'
-version = sphinx.__released__
+version = sphinx.__display_version__
 release = version
 show_authors = True
 

doc/config.rst

@@ -765,12 +765,6 @@ that use Sphinx's HTMLWriter class.
    The empty string is equivalent to ``'%b %d, %Y'`` (or a
    locale-dependent equivalent).
 
-.. confval:: html_use_smartypants
-
-   If true, `SmartyPants <http://daringfireball.net/projects/smartypants/>`_
-   will be used to convert quotes and dashes to typographically correct
-   entities.  Default: ``True``.
-
 .. confval:: html_add_permalinks
 
    Sphinx will add "permalinks" for each heading and description environment as
@@ -1615,26 +1609,6 @@ These options influence LaTeX output. See further :doc:`latex`.
       value selected the ``'inline'`` display.  For backwards compatibility,
       ``True`` is still accepted.
 
-.. confval:: latex_keep_old_macro_names
-
-   If ``True`` the ``\strong``, ``\code``, ``\bfcode``, ``\email``,
-   ``\tablecontinued``, ``\titleref``, ``\menuselection``, ``\accelerator``,
-   ``\crossref``, ``\termref``, and ``\optional`` text styling macros are
-   pre-defined by Sphinx and may be user-customized by some
-   ``\renewcommand``'s inserted either via ``'preamble'`` key or :dudir:`raw
-   <raw-data-pass-through>` directive. If ``False``, only ``\sphinxstrong``,
-   etc... macros are defined (and may be redefined by user).
-
-   The default is ``False`` as it prevents macro name conflicts caused by
-   latex packages. For example (``lualatex`` or ``xelatex``) ``fontspec v2.6``
-   has its own ``\strong`` macro.
-
-   .. versionadded:: 1.4.5
-   .. versionchanged:: 1.6
-      Default was changed from ``True`` to ``False``.
-   .. deprecated:: 1.6
-      This setting will be removed at Sphinx 1.7.
-
 .. confval:: latex_use_latex_multicolumn
 
    If ``False`` (default), the LaTeX writer uses for merged cells in grid

doc/domains.rst

@@ -563,7 +563,7 @@ a visibility statement (``public``, ``private`` or ``protected``).
 
       .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
 
-   A template class can be declared::
+   A class template can be declared::
 
       .. cpp:class:: template<typename T, std::size_t N> std::array
 
@@ -728,6 +728,17 @@ a visibility statement (``public``, ``private`` or ``protected``).
          Proxy to an element of a notional sequence that can be compared,
          indirected, or incremented.
 
+         **Notation**
+
+         .. cpp:var:: It r
+
+            An lvalue.
+
+         **Valid Expressions**
+
+         - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
+         - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` is incrementable.
+
       .. cpp:concept:: template<typename Cont> std::Container()
 
          Holder of elements, to which it can provide access via
@@ -740,6 +751,17 @@ a visibility statement (``public``, ``private`` or ``protected``).
       Proxy to an element of a notional sequence that can be compared,
       indirected, or incremented.
 
+      **Notation**
+
+      .. cpp:var:: It r
+
+         An lvalue.
+
+      **Valid Expressions**
+
+      - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
+      - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` is incrementable.
+
    .. cpp:concept:: template<typename Cont> std::Container()
 
       Holder of elements, to which it can provide access via
@@ -807,6 +829,30 @@ compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction
 even though it would not be valid C++.
 
 
+Inline Expressions and Tpes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rst:role:: cpp:expr
+
+   A role for inserting a C++ expression or type as inline text.
+   For example::
+
+      .. cpp:var:: int a = 42
+
+      .. cpp:function:: int f(int i)
+
+      An expression: :cpp:expr:`a * f(a)`.
+      A type: :cpp:expr:`const MySortedContainer<int>&`.
+
+   will be rendered as follows:
+
+  .. cpp:var:: int a = 42
+
+  .. cpp:function:: int f(int i)
+
+  An expression: :cpp:expr:`a * f(a)`.
+  A type: :cpp:expr:`const MySortedContainer<int>&`.
+
 Namespacing
 ~~~~~~~~~~~~~~~~~
 
@@ -842,7 +888,7 @@ directive.
 
       .. cpp:function:: std::size_t size() const
 
-   declares ``size`` as a member function of the template class ``std::vector``.
+   declares ``size`` as a member function of the class template ``std::vector``.
    Equivalently this could have been declared using::
 
       .. cpp:class:: template<typename T> \
@@ -922,7 +968,7 @@ These roles link to the given declaration types:
 .. admonition:: Note on References with Templates Parameters/Arguments
 
    Sphinx's syntax to give references a custom title can interfere with
-   linking to template classes, if nothing follows the closing angle
+   linking to class templates, if nothing follows the closing angle
    bracket, i.e. if the link looks like this: ``:cpp:class:`MyClass<int>```.
    This is interpreted as a link to ``int`` with a title of ``MyClass``.
    In this case, please escape the opening angle bracket with a backslash,
@@ -961,7 +1007,7 @@ In general the reference must include the template paraemter declarations, e.g.,
 Currently the lookup only succeed if the template parameter identifiers are equal strings. That is,
 ``template\<typename UOuter> Wrapper::Outer`` will not work.
 
-The inner template class can not be directly referenced, unless the current namespace
+The inner class template can not be directly referenced, unless the current namespace
 is changed or the following shorthand is used.
 If a template parameter list is omitted, then the lookup will assume either a template or a non-template,
 but not a partial template specialisation.

doc/latex.rst

@@ -414,19 +414,7 @@ Let us now list some macros from the package file
 - text styling commands (they have one argument): ``\sphinx<foo>`` with
   ``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``,
   ``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``,
-  ``optional``. The non-prefixed macros will still be defined if option
-  :confval:`latex_keep_old_macro_names` has been set to ``True`` (default is
-  ``False``), in which case the prefixed macros expand to the
-  non-prefixed ones.
-
-  .. versionadded:: 1.4.5
-     Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
-     with LaTeX packages.
-  .. versionchanged:: 1.6
-     The default value of :confval:`latex_keep_old_macro_names` changes to
-     ``False``, and even if set to ``True``, if a non-prefixed macro
-     already exists at ``sphinx.sty`` loading time, only the ``\sphinx``
-     prefixed one will be defined. The setting will be removed at 1.7.
+  ``optional``.
 
 - more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of
   ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
@@ -438,7 +426,14 @@ Let us now list some macros from the package file
      the new macros are wrappers of the formerly hard-coded ``\texttt``,
      ``\emph``, ... The default definitions can be found in
      :file:`sphinx.sty`.
-- paragraph level environments: for each admonition type ``<foo>``, the
+- a :dudir:`figure` may have an optional legend with arbitrary body
+  elements: they are rendered in a ``sphinxlegend`` environment. The default
+  definition issues ``\small``, and ends with ``\par``.
+
+  .. versionadded:: 1.5.6
+     formerly, the ``\small`` was hardcoded in LaTeX writer and the ending
+     ``\par`` was lacking.
+- for each admonition type ``<foo>``, the
   used environment is named ``sphinx<foo>``. They may be ``\renewenvironment``
   'd individually, and must then be defined with one argument (it is the heading
   of the notice, for example ``Warning:`` for :dudir:`warning` directive, if

doc/theming.rst

@@ -47,7 +47,9 @@ file :file:`blue.zip`, you can put it right in the directory containing
     html_theme_path = ["."]
 
 The third form is a python package.  If a theme you want to use is distributed
-as a python package, you can use it after installing::
+as a python package, you can use it after installing
+
+.. code-block:: bash
 
     # installing theme package
     $ pip install sphinxjp.themes.dotted