Merge branch 'stable' into 1.6-release

CHANGES

@@ -251,6 +251,8 @@ Bugs fixed
 * #3657: EPUB builder crashes if document startswith genindex exists
 * #3588: No compact (p tag) html output in the i18n document build even when
   :confval:`html_compact_lists` is True.
+* #3685: AttributeError when using 3rd party domains
+* #3702: LaTeX writer styles figure legends with a hard-coded ``\small``
 
 Testing
 --------
@@ -451,10 +453,8 @@ Incompatible changes
 * QtHelpBuilder doens't generate search page (ref: #2352)
 * QtHelpBuilder uses ``nonav`` theme instead of default one
   to improve readability.
-* latex: To provide good default settings to Japanese docs, Sphinx uses ``jsbook``
-  as a docclass by default if the ``language`` is ``ja``.
-* latex: To provide good default settings to Japanese docs, Sphinx uses
-  ``jreport`` and ``jsbooks`` as a docclass by default if the ``language`` is
+* latex: To provide good default settings to Japanese documents, Sphinx uses
+  ``jreport`` and ``jsbook`` as docclass if :confval:`language` is
   ``ja``.
 * ``sphinx-quickstart`` now allows a project version is empty
 * Fix :download: role on epub/qthelp builder. They ignore the role because they don't support it.
@@ -494,6 +494,7 @@ Incompatible changes
 * Emit warnings that will be deprecated in Sphinx 1.6 by default.
   Users can change the behavior by setting the environment variable
   PYTHONWARNINGS. Please refer :ref:`when-deprecation-warnings-are-displayed`.
+* #2454: new JavaScript variable ``SOURCELINK_SUFFIX`` is added
 
 Deprecated
 ----------

doc/latex.rst

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

sphinx/texinputs/sphinx.sty

@@ -1406,6 +1406,8 @@
 \protected\def\sphinxstyleliteralstrong  {\sphinxbfcode}
 \protected\def\sphinxstyleabbreviation   {\textsc}
 \protected\def\sphinxstyleliteralintitle {\sphinxcode}
+% figure legend comes after caption and may contain arbitrary body elements
+\newenvironment{sphinxlegend}{\par\small}{\par}
 
 % Tell TeX about pathological hyphenation cases:
 \hyphenation{Base-HTTP-Re-quest-Hand-ler}

sphinx/util/docfields.py

@@ -359,7 +359,8 @@ class DocFieldTransformer(object):
             else:
                 fieldtype, content = entry
                 fieldtypes = types.get(fieldtype.name, {})
+                env = self.directive.state.document.settings.env
                 new_list += fieldtype.make_field(fieldtypes, self.directive.domain,
-                                                 content, env=self.directive.env)
+                                                 content, env=env)
 
         node.replace_self(new_list)

sphinx/writers/latex.py

@@ -1833,12 +1833,10 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.unrestrict_footnote(node)
 
     def visit_legend(self, node):
-        # type: (nodes.Node) -> None
-        self.body.append('{\\small ')
+        self.body.append('\n\\begin{sphinxlegend}')
 
     def depart_legend(self, node):
-        # type: (nodes.Node) -> None
-        self.body.append('}')
+        self.body.append('\\end{sphinxlegend}\n')
 
     def visit_admonition(self, node):
         # type: (nodes.Node) -> None