Merge branch '1.8'

(Resolved) Conflicts:
	sphinx/texinputs/sphinxmanual.cls

CHANGES

@@ -163,6 +163,10 @@ Deprecated
 Features added
 --------------
 
+* LaTeX: it is possible to insert custom material to appear on back of title
+  page, see discussion of ``'maketitle'`` key of :confval:`latex_elements`
+  (``'manual'`` docclass only)
+
 Bugs fixed
 ----------
 
@@ -178,6 +182,11 @@ Bugs fixed
 * #5636: C++, fix parsing of floating point literals.
 * #5496 (again): C++, fix assertion in partial builds with duplicates.
 * #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
+* #1956: Default conf.py is not PEP8-compliant
+* #5849: LaTeX: document class ``\maketitle`` is overwritten with no
+  possibility to use original meaning in place of Sphinx custom one
+* #5834: apidoc: wrong help for ``--tocfile``
+* #5800: todo: crashed if todo is defined in TextElement
 
 Testing
 --------

doc/latex.rst

@@ -395,8 +395,20 @@ Macros
 
   .. versionchanged:: 1.5
      formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
-- the ``\maketitle`` command is redefined by the class files
+- a custom ``\sphinxmaketitle`` is defined in the class files
-  :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
+  :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls` and is used as
+  default setting of ``'maketitle'`` :confval:`latex_elements` key.
+
+  .. versionchanged:: 1.8.3
+     formerly, ``\maketitle`` from LaTeX document class was modified by
+     Sphinx.
+- for ``'manual'`` docclass a macro ``\sphinxbackoftitlepage``, if it is
+  defined, gets executed at end of ``\sphinxmaketitle``, before the final
+  ``\clearpage``.  Use either the ``'maketitle'`` key or the ``'preamble'`` key
+  of :confval:`latex_elements` to add a custom definition of
+  ``\sphinxbackoftitlepage``.
+
+  .. versionadded:: 1.8.3
 - the citation reference is typeset via ``\sphinxcite`` which is a wrapper
   of standard ``\cite``.
 

doc/usage/configuration.rst

@@ -2279,10 +2279,22 @@ information.
            Previously this was done from inside :file:`sphinx.sty`.
 
      ``'maketitle'``
-        "maketitle" call, default ``'\\maketitle'`` (but it has been
+        "maketitle" call, default ``'\\sphinxmaketitle'``. Override
-        redefined by the Sphinx ``manual`` and ``howto`` classes.) Override
+        if you want to generate a differently styled title page.
-        if you want to generate a differently-styled title page.
 
+        .. hint::
+
+           If the key value is set to
+           ``r'\newcommand\sphinxbackoftitlepage{<Extra
+           material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
+           typeset on back of title page (``'manual'`` docclass only).
+
+        .. versionchanged:: 1.8.3
+           Original ``\maketitle`` from document class is not overwritten,
+           hence is re-usable as part of some custom setting for this key.
+        .. versionadded:: 1.8.3
+           ``\sphinxbackoftitlepage`` optional macro.  It can also be defined
+           inside ``'preamble'`` key rather than this one.
      ``'releasename'``
         value that prefixes ``'release'`` element on title page, default
         ``'Release'``. As for *title* and *author* used in the tuples of

sphinx/ext/apidoc.py

@@ -336,7 +336,7 @@ Note: By default this script will not overwrite already created files."""))
                         dest='includeprivate',
                         help=__('include "_private" modules'))
     parser.add_argument('--tocfile', action='store', dest='tocfile', default='modules',
-                        help=__("don't create a table of contents file"))
+                        help=__("filename of table of contents (default: modules)"))
     parser.add_argument('-T', '--no-toc', action='store_false', dest='tocfile',
                         help=__("don't create a table of contents file"))
     parser.add_argument('-E', '--no-headings', action='store_true',

sphinx/ext/todo.py

@@ -173,7 +173,10 @@ def process_todo_nodes(app, doctree, fromdocname):
             try:
                 newnode['refuri'] = app.builder.get_relative_uri(
                     fromdocname, todo_info['docname'])
-                newnode['refuri'] += '#' + todo_info['target']['refid']
+                if 'refid' in todo_info['target']:
+                    newnode['refuri'] += '#' + todo_info['target']['refid']
+                else:
+                    newnode['refuri'] += '#' + todo_info['target']['ids'][0]
             except NoUri:
                 # ignore if no URI can be determined, e.g. for LaTeX output
                 pass

sphinx/templates/quickstart/conf.py_t

@@ -167,3 +167,4 @@ intersphinx_mapping = {'https://docs.python.org/': None}
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 {%- endif %}
+

sphinx/texinputs/sphinxhowto.cls

@@ -3,7 +3,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{sphinxhowto}[2018/09/18 v1.8.1 Document class (Sphinx HOWTO)]
+\ProvidesClass{sphinxhowto}[2018/12/22 v1.8.3 Document class (Sphinx howto)]
 
 % 'oneside' option overriding the 'twoside' default
 \newif\if@oneside
@@ -30,7 +30,7 @@
 % Change the title page to look a bit better, and fit in with the fncychap
 % ``Bjarne'' style a bit better.
 %
-\renewcommand{\maketitle}{%
+\newcommand{\sphinxmaketitle}{%
   \noindent\rule{\textwidth}{1pt}\par
     \begingroup % for PDF information dictionary
        \def\endgraf{ }\def\and{\& }%

sphinx/texinputs/sphinxmanual.cls

@@ -3,7 +3,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{sphinxmanual}[2018/09/18 v1.8.1 Document class (Sphinx manual)]
+\ProvidesClass{sphinxmanual}[2018/12/22 v1.8.3 Document class (Sphinx manual)]
 
 % chapters starting at odd pages (overridden by 'openany' document option)
 \PassOptionsToClass{openright}{\sphinxdocclass}
@@ -33,7 +33,7 @@
 % Change the title page to look a bit better, and fit in with the fncychap
 % ``Bjarne'' style a bit better.
 %
-\renewcommand{\maketitle}{%
+\renewcommand{\sphinxmaketitle}{%
   \let\sphinxrestorepageanchorsetting\relax
   \ifHy@pageanchor\def\sphinxrestorepageanchorsetting{\Hy@pageanchortrue}\fi
   \hypersetup{pageanchor=false}% avoid duplicate destination warnings
@@ -69,6 +69,8 @@
   \setcounter{footnote}{0}%
   \let\thanks\relax\let\maketitle\relax
   %\gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+  \clearpage
+  \ifdefined\sphinxbackoftitlepage\sphinxbackoftitlepage\fi
   \if@openright\cleardoublepage\else\clearpage\fi
   \sphinxrestorepageanchorsetting
 }

sphinx/writers/latex.py

@@ -159,7 +159,7 @@ DEFAULT_SETTINGS = {
     'releasename':     '',
     'makeindex':       '\\makeindex',
     'shorthandoff':    '',
-    'maketitle':       '\\maketitle',
+    'maketitle':       '\\sphinxmaketitle',
     'tableofcontents': '\\sphinxtableofcontents',
     'atendofbody':     '',
     'printindex':      '\\printindex',

tests/roots/test-ext-todo/foo.rst

@@ -2,3 +2,9 @@ foo
 ===
 
 .. todo:: todo in foo
+
+.. py:function:: hello()
+
+   :param bug: #5800
+
+               .. todo:: todo in param field

tests/test_ext_todo.py

@@ -40,13 +40,19 @@ def test_todo(app, status, warning):
             '<p class="last">todo in foo</p>')
     assert re.search(html, content, re.S)
 
+    html = ('<p class="first admonition-title">Todo</p>\n'
+            '<p class="last">todo in param field</p>')
+    assert re.search(html, content, re.S)
+
     # check emitted warnings
     assert 'WARNING: TODO entry found: todo in foo' in warning.getvalue()
     assert 'WARNING: TODO entry found: todo in bar' in warning.getvalue()
 
     # check handled event
-    assert len(todos) == 2
+    assert len(todos) == 3
-    assert set(todo[1].astext() for todo in todos) == set(['todo in foo', 'todo in bar'])
+    assert set(todo[1].astext() for todo in todos) == {'todo in foo',
+                                                       'todo in bar',
+                                                       'todo in param field'}
 
 
 @pytest.mark.sphinx('html', testroot='ext-todo', freshenv=True,
@@ -81,8 +87,10 @@ def test_todo_not_included(app, status, warning):
     assert 'WARNING: TODO entry found: todo in bar' in warning.getvalue()
 
     # check handled event
-    assert len(todos) == 2
+    assert len(todos) == 3
-    assert set(todo[1].astext() for todo in todos) == set(['todo in foo', 'todo in bar'])
+    assert set(todo[1].astext() for todo in todos) == {'todo in foo',
+                                                       'todo in bar',
+                                                       'todo in param field'}
 
 
 @pytest.mark.sphinx('latex', testroot='ext-todo', freshenv=True,
@@ -105,7 +113,7 @@ def test_todo_valid_link(app, status, warning):
     link = r'\{\\hyperref\[\\detokenize\{(.*?foo.*?)}]\{\\sphinxcrossref{' \
         r'\\sphinxstyleemphasis{original entry}}}}'
     m = re.findall(link, content)
-    assert len(m) == 2
+    assert len(m) == 4
     target = m[0]
 
     # Look for the targets of this link.