Merge branch 'master' into cpp-concepts

doc/conf.py

@@ -47,7 +47,7 @@ epub_fix_images = False
 epub_max_image_width = 0
 epub_show_urls = 'inline'
 epub_use_index = False
-epub_guide = (('toc', 'contents.html', u'Table of Contents'),)
+epub_guide = (('toc', 'contents.xhtml', u'Table of Contents'),)
 
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]

doc/config.rst

@@ -56,7 +56,7 @@ General configuration
 
 .. confval:: extensions
 
-   A list of strings that are module names of Sphinx extensions.  These can be
+   A list of strings that are module names of :ref:`extensions`. These can be
    extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones.
 
    Note that you can extend :data:`sys.path` within the conf file if your
@@ -870,6 +870,13 @@ that use Sphinx's HTMLWriter class.
 
    .. versionadded:: 0.6
 
+.. confval:: html_sourcelink_suffix
+
+   Suffix to be appended to source links (see :confval:`html_show_sourcelink`),
+   unless they have this suffix already.  Default is ``'.txt'``.
+
+   .. versionadded:: 1.5
+
 .. confval:: html_use_opensearch
 
    If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ description file will be
@@ -1460,7 +1467,17 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 Options for LaTeX output
 ------------------------
 
-These options influence LaTeX output.
+These options influence LaTeX output. See further :doc:`latex`.
+
+.. confval:: latex_engine
+
+   The LaTeX engine to build the docs.  The setting can have the following
+   values:
+
+   * pdflatex -- PDFLaTeX (default)
+   * xelatex -- XeLaTeX
+   * lualatex -- LuaLaTeX
+   * platex -- pLaTeX (default if `language` is 'ja')
 
 .. confval:: latex_documents
 
@@ -1568,6 +1585,21 @@ These options influence LaTeX output.
       value selected the ``'inline'`` display.  For backwards compatibility,
       ``True`` is still accepted.
 
+.. confval:: latex_keep_old_macro_names
+
+   If ``True`` (default) 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). Setting to
+   ``False`` may help solve macro name conflicts caused by user-added latex
+   packages.
+
+   .. versionadded:: 1.4.5
+
+
 .. confval:: latex_elements
 
    .. versionadded:: 0.5
@@ -1586,6 +1618,15 @@ These options influence LaTeX output.
      ``'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 ``'49336sp'`` which achieves
+        ``96px=1in`` (``1in = 72.27*65536 = 4736286.72sp``, and all dimensions
+        in TeX are internally integer multiples of ``sp``). To obtain for
+        example ``100px=1in``, one can use ``'0.01in'`` but it is more precise
+        to use ``'47363sp'``. To obtain ``72px=1in``, use ``'1bp'``.
+
+        .. versionadded:: 1.5
      ``'babel'``
         "babel" package inclusion, default ``'\\usepackage{babel}'``.
      ``'fontpkg'``
@@ -1608,7 +1649,7 @@ These options influence LaTeX output.
 
         .. versionadded:: 1.4
      ``'preamble'``
-        Additional preamble content, default empty.
+        Additional preamble content, default empty. See :doc:`latex`.
      ``'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
@@ -1627,7 +1668,7 @@ These options influence LaTeX output.
         ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex.
         Otherwise unset.
 
-        .. versionchanged:: 1.5
+        .. versionchanged:: 1.4.3
            Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
            compilers.
      ``'cmappkg'``
@@ -1678,6 +1719,11 @@ These options influence LaTeX output.
 
    .. versionadded:: 1.0
 
+   .. versionchanged:: 1.5
+
+      In Japanese docs(`language` is ``ja``), ``'jreport'`` is used for
+      ``'howto'`` and ``'jsbooks'`` is used for ``'manual'`` by default.
+
 .. confval:: latex_additional_files
 
    A list of file names, relative to the configuration directory, to copy to the
@@ -1953,3 +1999,33 @@ Options for the XML builder
        constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
        these all don't match slashes.  A double star ``**`` can be used to match
        any sequence of characters *including* slashes.
+
+
+.. _cpp-config:
+
+Options for the C++ domain
+--------------------------
+
+.. confval:: cpp_index_common_prefix
+
+   A list of prefixes that will be ignored when sorting C++ objects in the global index.
+   For example ``['awesome_lib::']``.
+
+   .. 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.
+
+   .. versionadded:: 1.5
+
+.. confval:: cpp_paren_attributes
+
+   A list of strings that the parser additionally should accept as attributes with one argument.
+   That is, if ``my_align_as`` is in the list, then ``my_align_as(X)`` is parsed as an attribute
+   for all strings ``X`` that have balanced brances (``()``, ``[]``, and ``{}``).
+   This can for example be used when attributes have been ``#define`` d for portability.
+
+   .. versionadded:: 1.5
+

doc/contents.rst

@@ -1,3 +1,4 @@
+
 .. _contents:
 
 Sphinx documentation contents
@@ -17,6 +18,7 @@ Sphinx documentation contents
    intl
    theming
    templating
+   latex
    extensions
    extdev/index
    websupport

doc/domains.rst

@@ -359,6 +359,18 @@ single word, like this::
    :param int priority: The priority of the message, can be a number 1-5
 
 
+.. versionadded:: 1.5
+
+Container types such as lists and dictionaries can be linked automatically
+using the following syntax::
+
+   :type priorities: list(int)
+   :type priorities: list[int]
+   :type mapping: dict(str, int)
+   :type mapping: dict[str, int]
+   :type point: tuple(float, float)
+   :type point: tuple[float, float]
+
 .. _python-roles:
 
 Cross-referencing Python objects
@@ -545,10 +557,10 @@ a visibility statement (``public``, ``private`` or ``protected``).
 
    Full and partial template specialisations can be declared::
 
-      .. cpp::class:: template<> \
+      .. cpp:class:: template<> \
                       std::array<bool, 256>
 
-      .. cpp::class:: template<typename T> \
+      .. cpp:class:: template<typename T> \
                       std::array<T, 42>
 
 
@@ -680,9 +692,9 @@ a visibility statement (``public``, ``private`` or ``protected``).
 
    Describe an enumerator, optionally with its value defined, e.g.,::
 
-      .. cpp::enumerator:: MyEnum::myEnumerator
+      .. cpp:enumerator:: MyEnum::myEnumerator
 
-      .. cpp::enumerator:: MyEnum::myOtherEnumerator = 42
+      .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
 
 
 .. rst:directive:: .. cpp:concept:: template-parameter-list name
@@ -972,6 +984,12 @@ References to partial specialisations must always include the template parameter
 Currently the lookup only succeed if the template parameter identifiers are equal strings.
 
 
+Configuration Variables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`cpp-config`.
+
+
 The Standard Domain
 -------------------
 

doc/ext/doctest.rst

@@ -182,7 +182,7 @@ The doctest extension uses the following configuration values:
 .. confval:: doctest_default_flags
 
    By default, these options are enabled:
-   
+
    - ``ELLIPSIS``, allowing you to put ellipses in the expected output that
      match anything in the actual output;
    - ``IGNORE_EXCEPTION_DETAIL``, causing everything following the leftmost

doc/ext/example_google.py

@@ -43,6 +43,39 @@ on the first line, separated by a colon.
 """
 
 
+def function_with_types_in_docstring(param1, param2):
+    """Example function with types documented in the docstring.
+
+    `PEP 484`_ type annotations are supported. If attribute, parameter, and
+    return types are annotated according to `PEP 484`_, they do not need to be
+    included in the docstring:
+
+    Args:
+        param1 (int): The first parameter.
+        param2 (str): The second parameter.
+
+    Returns:
+        bool: The return value. True for success, False otherwise.
+
+    .. _PEP 484:
+        https://www.python.org/dev/peps/pep-0484/
+
+    """
+
+
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    Args:
+        param1: The first parameter.
+        param2: The second parameter.
+
+    Returns:
+        The return value. True for success, False otherwise.
+
+    """
+
+
 def module_level_function(param1, param2=None, *args, **kwargs):
     """This is an example of a module level function.
 
@@ -50,9 +83,6 @@ def module_level_function(param1, param2=None, *args, **kwargs):
     of each parameter is required. The type and description of each parameter
     is optional, but should be included if not obvious.
 
-    Parameter types -- if given -- should be specified according to
-    `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
-
     If \*args or \*\*kwargs are accepted,
     they should be listed as ``*args`` and ``**kwargs``.
 
@@ -67,7 +97,7 @@ def module_level_function(param1, param2=None, *args, **kwargs):
 
     Args:
         param1 (int): The first parameter.
-        param2 (Optional[str]): The second parameter. Defaults to None.
+        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
             Second line of description should be indented.
         *args: Variable length argument list.
         **kwargs: Arbitrary keyword arguments.
@@ -94,10 +124,6 @@ def module_level_function(param1, param2=None, *args, **kwargs):
             that are relevant to the interface.
         ValueError: If `param2` is equal to `param1`.
 
-
-    .. _PEP 484:
-       https://www.python.org/dev/peps/pep-0484/
-
     """
     if param1 == param2:
         raise ValueError('param1 may not be equal to param2')
@@ -139,7 +165,7 @@ class ExampleError(Exception):
 
     Args:
         msg (str): Human readable string describing the exception.
-        code (Optional[int]): Error code.
+        code (:obj:`int`, optional): Error code.
 
     Attributes:
         msg (str): Human readable string describing the exception.
@@ -163,16 +189,9 @@ class ExampleClass(object):
     Properties created with the ``@property`` decorator should be documented
     in the property's getter method.
 
-    Attribute and property types -- if given -- should be specified according
-    to `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
-
     Attributes:
         attr1 (str): Description of `attr1`.
-        attr2 (Optional[int]): Description of `attr2`.
-
-
-    .. _PEP 484:
-       https://www.python.org/dev/peps/pep-0484/
+        attr2 (:obj:`int`, optional): Description of `attr2`.
 
     """
 
@@ -190,20 +209,20 @@ class ExampleClass(object):
 
         Args:
             param1 (str): Description of `param1`.
-            param2 (Optional[int]): Description of `param2`. Multiple
+            param2 (:obj:`int`, optional): Description of `param2`. Multiple
                 lines are supported.
-            param3 (List[str]): Description of `param3`.
+            param3 (list(str)): Description of `param3`.
 
         """
         self.attr1 = param1
         self.attr2 = param2
         self.attr3 = param3  #: Doc comment *inline* with attribute
 
-        #: List[str]: Doc comment *before* attribute, with type specified
+        #: list(str): Doc comment *before* attribute, with type specified
         self.attr4 = ['attr4']
 
         self.attr5 = None
-        """Optional[str]: Docstring *after* attribute, with type specified."""
+        """str: Docstring *after* attribute, with type specified."""
 
     @property
     def readonly_property(self):
@@ -212,8 +231,8 @@ class ExampleClass(object):
 
     @property
     def readwrite_property(self):
-        """List[str]: Properties with both a getter and setter should only
-        be documented in their getter method.
+        """list(str): Properties with both a getter and setter
+        should only be documented in their getter method.
 
         If the setter method contains notable behavior, it should be
         mentioned here.

doc/ext/example_google.rst

@@ -9,7 +9,9 @@ Example Google Style Python Docstrings
 
    :ref:`example_numpy`
 
-Download: :download:`example_google.py <example_google.py>`
+.. only:: builder_html
+
+   Download: :download:`example_google.py <example_google.py>`
 
 .. literalinclude:: example_google.py
    :language: python

doc/ext/example_numpy.py

@@ -37,6 +37,7 @@ module_level_variable1 : int
     one convention to document module level variables and be consistent
     with it.
 
+
 .. _NumPy Documentation HOWTO:
    https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
 
@@ -52,6 +53,52 @@ on the first line, separated by a colon.
 """
 
 
+def function_with_types_in_docstring(param1, param2):
+    """Example function with types documented in the docstring.
+
+    `PEP 484`_ type annotations are supported. If attribute, parameter, and
+    return types are annotated according to `PEP 484`_, they do not need to be
+    included in the docstring:
+
+    Parameters
+    ----------
+    param1 : int
+        The first parameter.
+    param2 : str
+        The second parameter.
+
+    Returns
+    -------
+    bool
+        True if successful, False otherwise.
+
+    .. _PEP 484:
+        https://www.python.org/dev/peps/pep-0484/
+
+    """
+
+
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    The return type must be duplicated in the docstring to comply
+    with the NumPy docstring style.
+
+    Parameters
+    ----------
+    param1
+        The first parameter.
+    param2
+        The second parameter.
+
+    Returns
+    -------
+    bool
+        True if successful, False otherwise.
+
+    """
+
+
 def module_level_function(param1, param2=None, *args, **kwargs):
     """This is an example of a module level function.
 
@@ -59,9 +106,6 @@ def module_level_function(param1, param2=None, *args, **kwargs):
     The name of each parameter is required. The type and description of each
     parameter is optional, but should be included if not obvious.
 
-    Parameter types -- if given -- should be specified according to
-    `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
-
     If \*args or \*\*kwargs are accepted,
     they should be listed as ``*args`` and ``**kwargs``.
 
@@ -81,7 +125,7 @@ def module_level_function(param1, param2=None, *args, **kwargs):
     ----------
     param1 : int
         The first parameter.
-    param2 : Optional[str]
+    param2 : :obj:`str`, optional
         The second parameter.
     *args
         Variable length argument list.
@@ -113,10 +157,6 @@ def module_level_function(param1, param2=None, *args, **kwargs):
     ValueError
         If `param2` is equal to `param1`.
 
-
-    .. _PEP 484:
-       https://www.python.org/dev/peps/pep-0484/
-
     """
     if param1 == param2:
         raise ValueError('param1 may not be equal to param2')
@@ -166,7 +206,7 @@ class ExampleError(Exception):
     ----------
     msg : str
         Human readable string describing the exception.
-    code : Optional[int]
+    code : :obj:`int`, optional
         Numeric error code.
 
     Attributes
@@ -194,20 +234,13 @@ class ExampleClass(object):
     Properties created with the ``@property`` decorator should be documented
     in the property's getter method.
 
-    Attribute and property types -- if given -- should be specified according
-    to `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
-
     Attributes
     ----------
     attr1 : str
         Description of `attr1`.
-    attr2 : Optional[int]
+    attr2 : :obj:`int`, optional
         Description of `attr2`.
 
-
-    .. _PEP 484:
-       https://www.python.org/dev/peps/pep-0484/
-
     """
 
     def __init__(self, param1, param2, param3):
@@ -227,10 +260,10 @@ class ExampleClass(object):
         ----------
         param1 : str
             Description of `param1`.
-        param2 : List[str]
+        param2 : list(str)
             Description of `param2`. Multiple
             lines are supported.
-        param3 : Optional[int]
+        param3 : :obj:`int`, optional
             Description of `param3`.
 
         """
@@ -238,11 +271,11 @@ class ExampleClass(object):
         self.attr2 = param2
         self.attr3 = param3  #: Doc comment *inline* with attribute
 
-        #: List[str]: Doc comment *before* attribute, with type specified
+        #: list(str): Doc comment *before* attribute, with type specified
         self.attr4 = ["attr4"]
 
         self.attr5 = None
-        """Optional[str]: Docstring *after* attribute, with type specified."""
+        """str: Docstring *after* attribute, with type specified."""
 
     @property
     def readonly_property(self):
@@ -251,8 +284,8 @@ class ExampleClass(object):
 
     @property
     def readwrite_property(self):
-        """List[str]: Properties with both a getter and setter should only
-        be documented in their getter method.
+        """list(str): Properties with both a getter and setter
+        should only be documented in their getter method.
 
         If the setter method contains notable behavior, it should be
         mentioned here.

doc/ext/example_numpy.rst

@@ -9,7 +9,9 @@ Example NumPy Style Python Docstrings
 
    :ref:`example_google`
 
-Download: :download:`example_numpy.py <example_numpy.py>`
+.. only:: builder_html
+
+   Download: :download:`example_numpy.py <example_numpy.py>`
 
 .. literalinclude:: example_numpy.py
    :language: python

doc/ext/inheritance.rst

@@ -40,7 +40,7 @@ It adds this directive:
       included.
 
    .. versionchanged:: 1.5
-      Added ``caption`` option 
+      Added ``caption`` option
 
 
 New config values are:

doc/ext/napoleon.rst

@@ -186,11 +186,60 @@ not be mixed. Choose one style for your project and be consistent with it.
    * :ref:`example_google`
    * :ref:`example_numpy`
 
-   For Python type annotations, see `PEP 484`_.
+
+Type Annotations
+----------------
+
+`PEP 484`_ introduced a standard way to express types in Python code.
+This is an alternative to expressing types directly in docstrings.
+One benefit of expressing types according to `PEP 484`_ is that
+type checkers and IDEs can take advantage of them for static code
+analysis.
+
+Google style with Python 3 type annotations::
+
+    def func(arg1: int, arg2: str) -> bool:
+        """Summary line.
+
+        Extended description of function.
+
+        Args:
+            arg1: Description of arg1
+            arg2: Description of arg2
+
+        Returns:
+            Description of return value
+
+        """
+        return True
+
+Google style with types in docstrings::
+
+    def func(arg1, arg2):
+        """Summary line.
+
+        Extended description of function.
+
+        Args:
+            arg1 (int): Description of arg1
+            arg2 (str): Description of arg2
+
+        Returns:
+            bool: Description of return value
+
+        """
+        return True
+
+.. Note::
+   `Python 2/3 compatible annotations`_ aren't currently
+   supported by Sphinx and won't show up in the docs.
 
 .. _PEP 484:
    https://www.python.org/dev/peps/pep-0484/
 
+.. _Python 2/3 compatible annotations:
+   https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+
 
 Configuration
 =============
@@ -208,6 +257,7 @@ enabled in `conf.py`::
     # Napoleon settings
     napoleon_google_docstring = True
     napoleon_numpy_docstring = True
+    napoleon_include_init_with_doc = False
     napoleon_include_private_with_doc = False
     napoleon_include_special_with_doc = True
     napoleon_use_admonition_for_examples = False
@@ -234,6 +284,23 @@ enabled in `conf.py`::
    True to parse `NumPy style`_ docstrings. False to disable support
    for NumPy style docstrings. *Defaults to True.*
 
+.. confval:: napoleon_include_init_with_doc
+
+   True to list ``__init___`` docstrings separately from the class
+   docstring. False to fall back to Sphinx's default behavior, which
+   considers the ``__init___`` docstring as part of the class
+   documentation. *Defaults to False.*
+
+   **If True**::
+
+       def __init__(self):
+           \"\"\"
+           This will be included in the docs because it has a docstring
+           \"\"\"
+
+       def __init__(self):
+           # This will NOT be included in the docs
+
 .. confval:: napoleon_include_private_with_doc
 
    True to include private members (like ``_membername``) with docstrings

doc/ext/todo.rst

@@ -34,6 +34,13 @@ There is also an additional config value:
    If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output,
    else they produce nothing.  The default is ``False``.
 
+.. confval:: todo_emit_warnings
+
+   If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries.
+   The default is ``False``.
+
+   .. versionadded:: 1.5
+
 .. confval:: todo_link_only
 
    If this is ``True``, :rst:dir:`todolist` produce output without file path and line,
@@ -41,3 +48,11 @@ There is also an additional config value:
 
    .. versionadded:: 1.4
 
+autodoc provides the following an additional event:
+
+.. event:: todo-defined (app, node)
+
+   .. versionadded:: 1.5
+
+   Emitted when a todo is defined. *node* is the defined ``sphinx.ext.todo.todo_node``
+   node.

doc/ext/viewcode.rst

@@ -15,6 +15,11 @@ a highlighted version of the source code, and a link will be added to all object
 descriptions that leads to the source code of the described object.  A link back
 from the source to the description will also be inserted.
 
+This extension works only on HTML related builders like ``html``,
+``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except
+``singlehtml``. By default ``epub`` builder doesn't
+support this extension (see :confval:`viewcode_enable_epub`).
+
 There is an additional config value:
 
 .. confval:: viewcode_import
@@ -34,3 +39,26 @@ There is an additional config value:
       main routine is protected by a ``if __name__ == '__main__'`` condition.
 
    .. versionadded:: 1.3
+
+.. confval:: viewcode_enable_epub
+
+   If this is ``True``, viewcode extension is also enabled even if you use
+   epub builders. This extension generates pages outside toctree, but this
+   is not preferred as epub format.
+
+   Until 1.4.x, this extension is always enabled. If you want to generate
+   epub as same as 1.4.x, you should set ``True``, but epub format checker's
+   score becomes worse.
+
+   The default is ``False``.
+
+   .. versionadded:: 1.5
+
+   .. warning::
+
+      Not all epub readers support pages generated by viewcode extension.
+      These readers ignore links to pages are not under toctree.
+
+      Some reader's rendering result are corrupted and
+      `epubcheck <https://github.com/IDPF/epubcheck>`_'s score
+      becomes worse even if the reader supports.

doc/install.rst

@@ -135,7 +135,7 @@ install.
 .. note::
 
    ``pip`` has been contained in the Python official installation after version
-    of Python-3.4.0 or Python-2.7.9.
+   of Python-3.4.0 or Python-2.7.9.
 
 
 Installing Sphinx with pip

doc/latex.rst

@@ -0,0 +1,151 @@
+.. highlightlang:: python
+
+.. _latex:
+
+LaTeX customization
+===================
+
+.. module:: latex
+   :synopsis: LaTeX specifics.
+
+The *latex* target does not (yet) benefit from pre-prepared themes like the
+*html* target does (see :doc:`theming`).
+
+There are two principal means of setting up customization:
+
+#. usage of the :ref:`latex-options` as described in :doc:`config`, particularly the
+   various keys of :confval:`latex_elements`, to modify the loaded packages,
+   for example::
+
+        'fontpkg':  '\\usepackage{times}',            # can load other font
+        'fncychap': '\\usepackage[Bjarne]{fncychap}', # can use other option
+
+   .. tip::
+
+      It is not mandatory to load *fncychap*. Naturally, without it and in
+      absence of further customizations, the chapter headings will revert to
+      LaTeX's default for the *report* class.
+
+#. usage of LaTeX ``\renewcommand``, ``\renewenvironment``, ``\setlength``,
+   ``\definecolor`` to modify the defaults from package file :file:`sphinx.sty`
+   and class files :file:`sphinxhowto.cls` and :file:`sphinxmanual.cls`. If such
+   definitions are few, they can be located inside the ``'preamble'`` key of
+   :confval:`latex_elements`. In case of many it may prove more convenient to
+   assemble them into a specialized file :file:`customizedmacros.tex` and use::
+
+       'preamble': '\\makeatletter\\input{customizedmacros.tex}\\makeatother',
+
+   More advanced LaTeX users will set up a style file
+   :file:`customizedmacros.sty`, which can then be loaded via::
+
+       'preamble': '\\usepackage{customizedmacros}',
+
+   The :ref:`build configuration file <build-config>` file will then have its variable
+   :confval:`latex_additional_files` appropriately configured, for example::
+
+       latex_additional_files = ["customizedmacros.sty"]
+
+   Such *LaTeX Sphinx theme* files could possibly be contributed in the
+   future by advanced users for wider use.
+
+Let us illustrate here what can be modified by the second method.
+
+- text styling commands (they have one argument): ``\sphinx<foo>`` with
+  ``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``,
+  ``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``,
+  ``optional``. By default and for backwards compatibility the ``\sphinx<foo>``
+  expands to ``\<foo>`` hence the user can choose to customize rather the latter
+  (the non-prefixed macros will be left undefined if option
+  :confval:`latex_keep_old_macro_names` is set to ``False`` in :file:`conf.py`.)
+
+  .. versionchanged:: 1.4.5
+     use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
+     with user added packages. The LaTeX writer uses always the prefixed names.
+- more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of
+  ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
+  ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``,
+  ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
+  ``abbreviation``, ``literalintitle``.
+
+  .. versionadded:: 1.5
+     earlier, the LaTeX writer used hard-coded ``\texttt``, ``\emph``, etc...
+- parameters for paragraph level environments: with ``<foo>`` one of
+  :dudir:`warning`, :dudir:`caution`, :dudir:`attention`,
+  :dudir:`danger`, :dudir:`error`, the colours
+  *sphinx<foo>bordercolor* and *sphinx<foo>bgcolor* can be
+  re-defined using ``\definecolor`` command. The
+  ``\sphinx<foo>border`` is a command (not a LaTeX length) which
+  specifies the thickness of the frame (default ``1pt``) and can be
+  ``\renewcommand`` 'd. The same applies with ``<foo>`` one of
+  :dudir:`note`, :dudir:`hint`, :dudir:`important`, :dudir:`tip`, but
+  the background colour is not implemented by the default environments
+  and the top and bottom rule thickness default is ``0.5pt``.
+
+  .. versionchanged:: 1.5
+     customizability of the parameters for each type of admonition.
+- paragraph level environments: for each admonition as in the previous item, 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
+  English is the document language). Their default definitions use either the
+  *sphinxheavybox* (for the first listed directives) or the *sphinxlightbox*
+  environments, configured to use the parameters (colours, border thickness)
+  specific to each type, as mentioned in the previous item.
+
+  .. versionchanged:: 1.5
+     use of public environment names, separate customizability of the parameters.
+- the :dudir:`contents` directive (with ``:local:`` option) and the
+  :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
+  Its default definition obeys three LaTeX lengths (not commands) as parameters:
+  ``\sphinxshadowsep`` (distance from contents), ``\sphinxshadowsize`` (width of
+  lateral shadow), ``\sphinxshadowrule`` (thickness of the frame).
+
+  .. versionchanged:: 1.5
+     use of public names for the three lengths. The environment itself was
+     redefined to allow page breaks at release 1.4.2.
+- the literal blocks (:rst:dir:`code-block` directives, etc ...), are
+  implemented using ``sphinxVerbatim`` environment which is a wrapper of
+  ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
+  of the top caption and the wrapping of long lines, and a frame which allows
+  pagebreaks. The LaTeX lengths (not commands) ``\sphinxverbatimsep`` and
+  ``\sphinxverbatimborder`` customize the framing. Inside tables the used
+  environment is ``sphinxVerbatimintable`` (it does not draw a frame, but
+  allows a caption).
+
+  .. versionchanged:: 1.5
+     ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (meaning
+     which is the one of ``OriginalVerbatim`` too), and custom one is called
+     ``sphinxVerbatim``. Also, earlier version of Sphinx used
+     ``OriginalVerbatim`` inside tables (captions were lost, long code lines
+     were not wrapped), they now use ``sphinxVerbatimintable``.
+  .. versionadded:: 1.5
+     the two customizable lengths, the ``sphinxVerbatimintable``.
+- by default the Sphinx style file ``sphinx.sty`` includes the command
+  ``\fvset{fontsize=\small}`` as part of its configuration of
+  ``fancyvrb.sty``. The user may override this for example via
+  ``\fvset{fontsize=auto}`` which will use for listings the ambient
+  font size. Refer to ``fancyvrb.sty``'s documentation for further keys.
+
+  .. versionadded:: 1.5
+     formerly, the use of ``\small`` for code listings was not customizable.
+- miscellaneous colours: *TitleColor*, *InnerLinkColor*, *OuterLinkColor*,
+  *VerbatimColor* (this is a background colour), *VerbatimBorderColor*.
+- the ``\sphinxAtStartFootnote`` is inserted between footnote numbers and their
+  texts, by default it does ``\mbox{ }``.
+- use ``\sphinxSetHeaderFamily`` to set the font used by headings
+  (default is ``\sffamily\bfseries``).
+
+  .. versionadded:: 1.5
+- the section, subsection, ...  headings are set using  *titlesec*'s
+  ``\titleformat`` command.
+- for the ``'manual'`` class, the chapter headings can be customized using
+  *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. Or, if
+  the loading of this package has been removed from ``'fncychap'`` key, one can
+  use the *titlesec* ``\titleformat`` command.
+
+.. note::
+
+   It is impossible to revert or prevent the loading of a package that results
+   from a ``\usepackage`` executed from inside the :file:`sphinx.sty` style
+   file. Sphinx aims at loading as few packages as are really needed for its
+   default design.

doc/markup/inline.rst

@@ -200,6 +200,12 @@ Referencing downloadable files
    The ``example.py`` file will be copied to the output directory, and a
    suitable link generated to it.
 
+   Not to show unavailable download links, you should wrap whole paragraphs that
+   have this role::
+
+      .. only:: builder_html
+
+         See :download:`this example script <../example.py>`.
 
 Cross-referencing figures by figure number
 ------------------------------------------

doc/rest.rst

@@ -363,8 +363,9 @@ directory on building (e.g. the ``_static`` directory for HTML output.)
 
 Interpretation of image size options (``width`` and ``height``) is as follows:
 if the size has no unit or the unit is pixels, the given size will only be
-respected for output channels that support pixels (i.e. not in LaTeX output).
-Other units (like ``pt`` for points) will be used for HTML and LaTeX output.
+respected for output channels that support pixels. Other units (like ``pt``
+for points) will be used for HTML and LaTeX output (the latter replaces ``pt``
+by ``bp`` as this is the TeX unit such that ``72bp=1in``).
 
 Sphinx extends the standard docutils behavior by allowing an asterisk for the
 extension::
@@ -386,6 +387,9 @@ Note that image file names should not contain spaces.
 .. versionchanged:: 0.6
    Image paths can now be absolute.
 
+.. versionchanged:: 1.5
+   latex target supports pixels (default is ``96px=1in``).
+
 
 Footnotes
 ---------

doc/theming.rst

@@ -81,6 +81,8 @@ that has to return the directory with themes in it::
 Builtin themes
 --------------
 
+.. cssclass:: longtable
+
 +--------------------+--------------------+
 | **Theme overview** |                    |
 +--------------------+--------------------+

doc/tutorial.rst

@@ -300,12 +300,17 @@ features of intersphinx.
 More topics to be covered
 -------------------------
 
-- Other extensions (math, viewcode, doctest)
+- :doc:`Other extensions <extensions>`:
+
+  * :doc:`ext/math`,
+  * :doc:`ext/viewcode`,
+  * :doc:`ext/doctest`,
+  * ...
 - Static files
-- Selecting a theme
-- Templating
+- :doc:`Selecting a theme <theming>`
+- :ref:`Templating <templating>`
 - Using extensions
-- Writing extensions
+- :ref:`Writing extensions <dev-extensions>`
 
 
 .. rubric:: Footnotes