IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into latex_tableofcontentshook

Browse Source
This commit is contained in:
jfbu 2018-12-23 11:31:10 +01:00
commit d4d1a4ba84
14 changed files with 76 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
CHANGES
View File

@ -168,6 +168,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
----------
@ -183,6 +187,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
--------

16
doc/latex.rst
View File

@ -404,8 +404,20 @@ Macros
done during loading of ``'manual'`` docclass are now executed later via
``\sphinxtableofcontentshook``. This macro is also executed by the
``'howto'`` docclass, but defaults to empty with it.
- 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``.

18
doc/usage/configuration.rst
View File

@ -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

2
sphinx/builders/html.py
View File

@ -1633,7 +1633,7 @@ def setup(app):
app.add_config_value('html_sidebars', {}, 'html')
app.add_config_value('html_additional_pages', {}, 'html')
app.add_config_value('html_domain_indices', True, 'html', [list])
app.add_config_value('html_add_permalinks', '\u00B6', 'html')
app.add_config_value('html_add_permalinks', '', 'html')
app.add_config_value('html_use_index', True, 'html')
app.add_config_value('html_split_index', False, 'html')
app.add_config_value('html_copy_source', True, 'html')

2
sphinx/ext/apidoc.py
View File

@ -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',

5
sphinx/ext/todo.py
View File

@ -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

1
sphinx/templates/quickstart/conf.py_t
View File

@ -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 %}

4
sphinx/texinputs/sphinxhowto.cls
View File

@ -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{\& }%

12
sphinx/texinputs/sphinxmanual.cls
View File

@ -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,9 +33,9 @@
% Change the title page to look a bit better, and fit in with the fncychap
% ``Bjarne'' style a bit better.
%
\renewcommand{\maketitle}{%
\let\spx@tempa\relax
\ifHy@pageanchor\def\spx@tempa{\Hy@pageanchortrue}\fi
\newcommand{\sphinxmaketitle}{%
\let\sphinxrestorepageanchorsetting\relax
\ifHy@pageanchor\def\sphinxrestorepageanchorsetting{\Hy@pageanchortrue}\fi
\hypersetup{pageanchor=false}% avoid duplicate destination warnings
\begin{titlepage}%
\let\footnotesize\small
@ -69,8 +69,10 @@
\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
\spx@tempa
\sphinxrestorepageanchorsetting
}
\newcommand{\sphinxtableofcontents}{%

2
sphinx/writers/html.py
View File

@ -92,7 +92,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self.permalink_text = self.config.html_add_permalinks
# support backwards-compatible setting to a bool
if not isinstance(self.permalink_text, str):
self.permalink_text = self.permalink_text and '\u00B6' or ''
self.permalink_text = self.permalink_text and '' or ''
self.permalink_text = self.encode(self.permalink_text)
self.secnumber_suffix = self.config.html_secnumber_suffix
self.param_separator = ''

2
sphinx/writers/html5.py
View File

@ -62,7 +62,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
self.permalink_text = self.config.html_add_permalinks
# support backwards-compatible setting to a bool
if not isinstance(self.permalink_text, str):
self.permalink_text = self.permalink_text and '\u00B6' or ''
self.permalink_text = self.permalink_text and '' or ''
self.permalink_text = self.encode(self.permalink_text)
self.secnumber_suffix = self.config.html_secnumber_suffix
self.param_separator = ''

2
sphinx/writers/latex.py
View File

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

6
tests/roots/test-ext-todo/foo.rst
View File

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

18
tests/test_ext_todo.py
View File

@ -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.