diff options
| -rw-r--r-- | CHANGES | 9 | ||||
| -rw-r--r-- | doc/latex.rst | 16 | ||||
| -rw-r--r-- | doc/usage/configuration.rst | 18 | ||||
| -rw-r--r-- | sphinx/ext/apidoc.py | 2 | ||||
| -rw-r--r-- | sphinx/ext/todo.py | 5 | ||||
| -rw-r--r-- | sphinx/templates/quickstart/conf.py_t | 1 | ||||
| -rw-r--r-- | sphinx/texinputs/sphinxhowto.cls | 4 | ||||
| -rw-r--r-- | sphinx/texinputs/sphinxmanual.cls | 6 | ||||
| -rw-r--r-- | sphinx/writers/latex.py | 2 | ||||
| -rw-r--r-- | tests/roots/test-ext-todo/foo.rst | 6 | ||||
| -rw-r--r-- | tests/test_ext_todo.py | 18 |
11 files changed, 70 insertions, 17 deletions
@@ -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 -------- diff --git a/doc/latex.rst b/doc/latex.rst index 63e860a64..0e2740d68 100644 --- a/doc/latex.rst +++ b/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 - :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`. +- a custom ``\sphinxmaketitle`` is defined in the class files + :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``. diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 3e20cf7dc..5400697eb 100644 --- a/doc/usage/configuration.rst +++ b/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 - redefined by the Sphinx ``manual`` and ``howto`` classes.) Override - if you want to generate a differently-styled title page. + "maketitle" call, default ``'\\sphinxmaketitle'``. Override + 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 diff --git a/sphinx/ext/apidoc.py b/sphinx/ext/apidoc.py index d0c87be13..c0c8c6bcb 100644 --- a/sphinx/ext/apidoc.py +++ b/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', diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index 62fea7df8..1d8f9cb60 100644 --- a/sphinx/ext/todo.py +++ b/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 diff --git a/sphinx/templates/quickstart/conf.py_t b/sphinx/templates/quickstart/conf.py_t index c43b219a3..bbeaeb8d4 100644 --- a/sphinx/templates/quickstart/conf.py_t +++ b/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 %} + diff --git a/sphinx/texinputs/sphinxhowto.cls b/sphinx/texinputs/sphinxhowto.cls index 64c2feb64..6e4858567 100644 --- a/sphinx/texinputs/sphinxhowto.cls +++ b/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{\& }% diff --git a/sphinx/texinputs/sphinxmanual.cls b/sphinx/texinputs/sphinxmanual.cls index 7d80b3b70..bc48b6260 100644 --- a/sphinx/texinputs/sphinxmanual.cls +++ b/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 } diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index c7f4388d6..a02e9a8ea 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -159,7 +159,7 @@ DEFAULT_SETTINGS = { 'releasename': '', 'makeindex': '\\makeindex', 'shorthandoff': '', - 'maketitle': '\\maketitle', + 'maketitle': '\\sphinxmaketitle', 'tableofcontents': '\\sphinxtableofcontents', 'atendofbody': '', 'printindex': '\\printindex', diff --git a/tests/roots/test-ext-todo/foo.rst b/tests/roots/test-ext-todo/foo.rst index 269199977..12e9f63c5 100644 --- a/tests/roots/test-ext-todo/foo.rst +++ b/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 diff --git a/tests/test_ext_todo.py b/tests/test_ext_todo.py index e5aff7598..5e7ade9f6 100644 --- a/tests/test_ext_todo.py +++ b/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 set(todo[1].astext() for todo in todos) == set(['todo in foo', 'todo in bar']) + assert len(todos) == 3 + 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 set(todo[1].astext() for todo in todos) == set(['todo in foo', 'todo in bar']) + assert len(todos) == 3 + 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. |