Merge branch 'stable'

CHANGES

@@ -108,13 +108,21 @@ Features added
 --------------
 
 * #4181: autodoc: Sort dictionary keys when possible
+* ``VerbatimHighlightColor`` is a new
+  :ref:`LaTeX 'sphinxsetup' <latexsphinxsetup>` key (refs: #4285)
 
 Bugs fixed
 ----------
 
 * #4206: latex: reST label between paragraphs loses paragraph break
 * #4231: html: Apply fixFirefoxAnchorBug only under Firefox
+* #4221: napoleon depends on autodoc, but users need to load it manually
 * #2298: automodule fails to document a class attribute
+* #4099: C++: properly link class reference to class from inside constructor
+* #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
+* #4249: PDF output: Pygments error highlighting increases line spacing in
+  code blocks
+* #1238: Support ``:emphasize-lines:`` in PDF output
 
 Testing
 --------

doc/ext/napoleon.rst

@@ -68,8 +68,8 @@ Getting Started
 
        # conf.py
 
-       # Add autodoc and napoleon to the extensions list
+       # Add napoleon to the extensions list
-       extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+       extensions = ['sphinx.ext.napoleon']
 
 2. Use `sphinx-apidoc` to build your API documentation::
 
@@ -246,13 +246,12 @@ Configuration
 
 Listed below are all the settings used by napoleon and their default
 values. These settings can be changed in the Sphinx `conf.py` file. Make
-sure that both "sphinx.ext.autodoc" and "sphinx.ext.napoleon" are
+sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
-enabled in `conf.py`::
 
     # conf.py
 
     # Add any Sphinx extension module names here, as strings
-    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+    extensions = ['sphinx.ext.napoleon']
 
     # Napoleon settings
     napoleon_google_docstring = True

doc/latex.rst

@@ -267,6 +267,11 @@ The available styling options
 ``VerbatimBorderColor``
     default ``{rgb}{0,0,0}``. The frame color, defaults to black.
 
+``VerbatimHighlightColor``
+    default ``{rgb}{0.878,1,1}``. The color for highlighted lines.
+
+    .. versionadded:: 1.6.6
+
 ``verbatimsep``
     default ``\fboxsep``. The separation between code lines and the frame.
 

doc/markup/code.rst

@@ -121,6 +121,8 @@ emphasize particular lines::
 .. versionchanged:: 1.3
    ``lineno-start`` has been added.
 
+.. versionchanged:: 1.6.6
+   LaTeX supports the ``emphasize-lines`` option.
 
 Includes
 ^^^^^^^^
@@ -188,8 +190,8 @@ Includes
    ``lines``, the first allowed line having by convention the line number ``1``.
 
    When lines have been selected in any of the ways described above, the
-   line numbers in ``emphasize-lines`` also refer to the selection, with the
+   line numbers in ``emphasize-lines`` refer to those selected lines, counted
-   first selected line having number ``1``.
+   consecutively starting at ``1``.
 
    When specifying particular parts of a file to display, it can be useful to
    display the original line numbers. This can be done using the

sphinx/domains/cpp.py

@@ -3575,8 +3575,8 @@ class Symbol(object):
                 return None
         return s
 
-    def find_name(self, nestedName, templateDecls, templateShorthand, matchSelf):
+    def find_name(self, nestedName, templateDecls, typ, templateShorthand, matchSelf):
-        # type: (Any, Any, Any, bool) -> Symbol
+        # type: (Any, Any, Any, Any, bool) -> Symbol
         # templateShorthand: missing template parameter lists for templates is ok
 
         # TODO: unify this with the _add_symbols
@@ -3594,7 +3594,14 @@ class Symbol(object):
             while parentSymbol.parent:
                 if parentSymbol.find_identifier(firstName.identifier,
                                                 matchSelf=matchSelf):
-                    break
+                    # if we are in the scope of a constructor but wants to reference the class
+                    # we need to walk one extra up
+                    if (len(names) == 1 and typ == 'class' and matchSelf and
+                            parentSymbol.parent and parentSymbol.parent.identifier and
+                            parentSymbol.parent.identifier == firstName.identifier):
+                        pass
+                    else:
+                        break
                 parentSymbol = parentSymbol.parent
         iTemplateDecl = 0
         for iName in range(len(names)):
@@ -5852,7 +5859,7 @@ class CPPDomain(Domain):
             templateDecls = ast.templatePrefix.templates
         else:
             templateDecls = []
-        s = parentSymbol.find_name(name, templateDecls,
+        s = parentSymbol.find_name(name, templateDecls, typ,
                                    templateShorthand=True,
                                    matchSelf=True)
         if s is None or s.declaration is None:

sphinx/ext/napoleon/__init__.py

@@ -27,13 +27,12 @@ class Config(object):
 
     Listed below are all the settings used by napoleon and their default
     values. These settings can be changed in the Sphinx `conf.py` file. Make
-    sure that both "sphinx.ext.autodoc" and "sphinx.ext.napoleon" are
+    sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
-    enabled in `conf.py`::
 
         # conf.py
 
         # Add any Sphinx extension module names here, as strings
-        extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+        extensions = ['sphinx.ext.napoleon']
 
         # Napoleon settings
         napoleon_google_docstring = True
@@ -294,6 +293,7 @@ def setup(app):
 
     _patch_python_domain()
 
+    app.setup_extension('sphinx.ext.autodoc')
     app.connect('autodoc-process-docstring', _process_docstring)
     app.connect('autodoc-skip-member', _skip_member)
 

sphinx/texinputs/sphinx.sty

@@ -6,7 +6,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2017/10/27 v1.7 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2017/12/11 v1.7 LaTeX package (Sphinx markup)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -39,7 +39,7 @@
 \@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
 % for \text macro and \iffirstchoice@ conditional even if amsmath not loaded
 \RequirePackage{amstext}
-\RequirePackage{textcomp}
+\RequirePackage[warn]{textcomp}
 \RequirePackage{titlesec}
 \@ifpackagelater{titlesec}{2016/03/15}%
  {\@ifpackagelater{titlesec}{2016/03/21}%
@@ -165,6 +165,7 @@
 % For highlighted code.
 \RequirePackage{fancyvrb}
 \fvset{fontsize=\small}
+\define@key{FV}{hllines}{\def\sphinx@verbatim@checkifhl##1{\in@{, ##1,}{#1}}}
 % For hyperlinked footnotes in tables; also for gathering footnotes from
 % topic and warning blocks. Also to allow code-blocks in footnotes.
 \RequirePackage{footnotehyper-sphinx}
@@ -214,6 +215,17 @@
 
 % stylesheet for highlighting with pygments
 \RequirePackage{sphinxhighlight}
+% fix baseline increase from Pygments latex formatter in case of error tokens
+% and keep \fboxsep's scope local via added braces
+\def\PYG@tok@err{%
+    \def\PYG@bc##1{{\setlength{\fboxsep}{-\fboxrule}%
+                    \fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}%
+}
+\def\PYG@tok@cs{%
+    \def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}%
+    \def\PYG@bc##1{{\setlength{\fboxsep}{0pt}%
+                    \colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}%
+}%
 
 
 %% OPTIONS
@@ -307,6 +319,8 @@
 \sphinxDeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}}
 \sphinxDeclareColorOption{VerbatimColor}{{rgb}{1,1,1}}
 \sphinxDeclareColorOption{VerbatimBorderColor}{{rgb}{0,0,0}}
+% also no prefix for this one, for consistency (sigh). Color as in minted!
+\sphinxDeclareColorOption{VerbatimHighlightColor}{{rgb}{0.878,1,1}}
 % now the colours defined with "sphinx" prefix in their names
 \newcommand*{\sphinxDeclareSphinxColorOption}[2]{%
    % set the initial default
@@ -851,6 +865,32 @@
 % needed to create wrapper environments of fancyvrb's Verbatim
 \newcommand*{\sphinxVerbatimEnvironment}{\gdef\FV@EnvironName{sphinxVerbatim}}
 \newcommand*{\sphinxverbatimsmallskipamount}{\smallskipamount}
+% serves to implement line highlighting and line wrapping
+\newcommand\sphinxFancyVerbFormatLine[1]{%
+  \expandafter\sphinx@verbatim@checkifhl
+    \expandafter{\the\numexpr\value{FancyVerbLine}-\spx@verbatim@linedelta}%
+  \ifin@
+     \edef\sphinx@restorefboxsep{\fboxsep\the\fboxsep\relax}%
+     \fboxsep\z@
+     \colorbox{VerbatimHighlightColor}%
+              {\sphinx@restorefboxsep\sphinx@FancyVerbFormatLine{#1}}%
+  \else
+     \sphinx@FancyVerbFormatLine{#1}%
+  \fi
+}%
+\def\sphinx@FancyVerbFormatLine@wrap #1%
+{\hsize\linewidth
+    \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
+          \doublehyphendemerits\z@\finalhyphendemerits\z@
+          \strut #1\strut}%
+}%
+\def\sphinx@FancyVerbFormatLine@nowrap #1{\hb@xt@\linewidth{\strut #1\hss}}%
+\def\sphinx@FancyVerbCodesHook
+   {\FV@SetLineNo\edef\spx@verbatim@linedelta{\the\value{FancyVerbLine}}}%
+\g@addto@macro\FV@SetupFont{%
+    \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
+    \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
+}%
 \newenvironment{sphinxVerbatim}{%
   % first, let's check if there is a caption
   \ifx\sphinxVerbatimTitle\empty
@@ -905,20 +945,20 @@
   %       to achieve this without extensive rewrite of fancyvrb.
   %     - The (not used in sphinx) obeytabs option to Verbatim is
   %       broken by this change (showtabs and tabspace work).
-  \expandafter\def\expandafter\FV@SetupFont\expandafter
+    \let\sphinx@FancyVerbFormatLine\sphinx@FancyVerbFormatLine@wrap
-    {\FV@SetupFont\sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
+    \let\FV@Space\spx@verbatim@space
-                  \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}}%
-  \def\FancyVerbFormatLine ##1{\hsize\linewidth
-          \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
-                \doublehyphendemerits\z@\finalhyphendemerits\z@
-                \strut ##1\strut}%
-          }%
-  \let\FV@Space\spx@verbatim@space
   % Allow breaks at special characters using \PYG... macros.
-  \sphinxbreaksatspecials
+    \sphinxbreaksatspecials
   % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation)
-  \def\FancyVerbCodes{\sphinxbreaksviaactive}%
+    \expandafter\def\expandafter\sphinx@FancyVerbCodesHook\expandafter
-  \fi % end of conditional code for wrapping long code lines
+                   {\sphinx@FancyVerbCodesHook\sphinxbreaksviaactive}%
+  \else % end of conditional code for wrapping long code lines
+    \let\sphinx@FancyVerbFormatLine\sphinx@FancyVerbFormatLine@nowrap
+  \fi
+  \let\FancyVerbFormatLine\sphinxFancyVerbFormatLine
+  % hook into \FancyVerbCodes to recover at first code line the numbering offset
+  \expandafter\def\expandafter\FancyVerbCodes\expandafter
+      {\FancyVerbCodes\sphinx@FancyVerbCodesHook}%
   % go around fancyvrb's check of \@currenvir
   \let\VerbatimEnvironment\sphinxVerbatimEnvironment
   % go around fancyvrb's check of current list depth

sphinx/writers/latex.py

@@ -2268,6 +2268,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
             lang = self.hlsettingstack[-1][0]
             linenos = code.count('\n') >= self.hlsettingstack[-1][1] - 1
             highlight_args = node.get('highlight_args', {})
+            hllines = '\\fvset{hllines={, %s,}}%%' %\
+                      str(highlight_args.get('hl_lines', []))[1:-1]
             if 'language' in node:
                 # code-block directives
                 lang = node['language']
@@ -2306,7 +2308,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 hlcode += '\\end{sphinxVerbatimintable}'
             else:
                 hlcode += '\\end{sphinxVerbatim}'
-            self.body.append('\n' + hlcode + '\n')
+            self.body.append('\n' + hllines + '\n' + hlcode + '\n')
             raise nodes.SkipNode
 
     def depart_literal_block(self, node):

tests/roots/test-directive-code/emphasize.rst

@@ -0,0 +1,7 @@
+Literal Includes with Highlighted Lines
+=======================================
+
+.. literalinclude:: target.py
+   :language: python
+   :emphasize-lines: 5-6, 13-15, 24-
+

tests/roots/test-latex-table/expects/longtable_having_verbatim.tex

@@ -27,6 +27,7 @@ header2
 
 \endlastfoot
 
+\fvset{hllines={, ,}}%
 \begin{sphinxVerbatimintable}[commandchars=\\\{\}]
 \PYG{n}{hello} \PYG{n}{world}
 \end{sphinxVerbatimintable}

tests/roots/test-latex-table/expects/table_having_verbatim.tex

@@ -10,6 +10,7 @@ header1
 header2
 \\
 \hline
+\fvset{hllines={, ,}}%
 \begin{sphinxVerbatimintable}[commandchars=\\\{\}]
 \PYG{n}{hello} \PYG{n}{world}
 \end{sphinxVerbatimintable}

tests/test_directive_code.py

@@ -349,6 +349,14 @@ def test_code_block_namedlink_latex(app, status, warning):
     assert link2 in latex
 
 
+@pytest.mark.sphinx('latex', testroot='directive-code')
+def test_code_block_emphasize_latex(app, status, warning):
+    app.builder.build(['emphasize'])
+    latex = (app.outdir / 'Python.tex').text(encoding='utf-8').replace('\r\n', '\n')
+    includes = '\\fvset{hllines={, 5, 6, 13, 14, 15, 24, 25, 26, 27,}}%\n'
+    assert includes in latex
+
+
 @pytest.mark.sphinx('xml', testroot='directive-code')
 def test_literal_include(app, status, warning):
     app.builder.build(['index'])

tests/test_markup.py

@@ -211,7 +211,8 @@ def get_verifier(verify, verify_re):
         'verify',
         u'::\n\n @Γ\\∞${}',
         None,
-        (u'\\begin{sphinxVerbatim}[commandchars=\\\\\\{\\}]\n'
+        (u'\\fvset{hllines={, ,}}%\n'
+         u'\\begin{sphinxVerbatim}[commandchars=\\\\\\{\\}]\n'
          u'@\\(\\Gamma\\)\\PYGZbs{}\\(\\infty\\)\\PYGZdl{}\\PYGZob{}\\PYGZcb{}\n'
          u'\\end{sphinxVerbatim}'),
     ),