mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge branch 'master' into refactor_highlighter
This commit is contained in:
Takeshi KOMIYA
GitHub
commit
9bb1e83668
2
AUTHORS
2
AUTHORS
@ -14,6 +14,7 @@ Other co-maintainers:
|
||||
* Takeshi Komiya <@tk0miya>
|
||||
* Jean-François Burnol <@jfbu>
|
||||
* Yoshiki Shibukawa <@shibu_jp>
|
||||
* Timotheus Kampik - <@TimKam>
|
||||
|
||||
Other contributors, listed alphabetically, are:
|
||||
|
||||
@ -37,7 +38,6 @@ Other contributors, listed alphabetically, are:
|
||||
* Zac Hatfield-Dodds -- doctest reporting improvements
|
||||
* Doug Hellmann -- graphviz improvements
|
||||
* Tim Hoffmann -- theme improvements
|
||||
* Timotheus Kampik - JS theme & search enhancements
|
||||
* Dave Kuhlman -- original LaTeX writer
|
||||
* Blaise Laflamme -- pyramid theme
|
||||
* Chris Lamb -- reproducibility fixes
|
||||
|
||||
6
CHANGES
6
CHANGES
@ -175,6 +175,7 @@ Features added
|
||||
if :confval:`latex_engine` is ``'xelatex'`` or ``'lualatex'``.
|
||||
* #4976: ``SphinxLoggerAdapter.info()`` now supports ``location`` parameter
|
||||
* #5122: setuptools: support nitpicky option
|
||||
* #2820: autoclass directive supports nested class
|
||||
* Apply :confval:`trim_doctest_flags` to all builders (cf. text, manpages)
|
||||
|
||||
Bugs fixed
|
||||
@ -188,6 +189,8 @@ Bugs fixed
|
||||
* #5132: (lualatex) PDF build fails if indexed word starts with Unicode character
|
||||
* #5133: latex: index headings "Symbols" and "Numbers" not internationalized
|
||||
* #5114: sphinx-build: Handle errors on scanning documents
|
||||
* epub: spine has been broken when "self" is listed on toctree (refs: #4611)
|
||||
* #344: autosummary does not understand docstring of module level attributes
|
||||
|
||||
Testing
|
||||
--------
|
||||
@ -221,6 +224,9 @@ Features added
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
* #5198: document not in toctree warning when including files only for parallel
|
||||
builds
|
||||
|
||||
Testing
|
||||
--------
|
||||
|
||||
|
||||
@ -150,7 +150,7 @@ These themes are:
|
||||
|
||||
- **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
|
||||
snippet that makes the sidebar collapsible via a button on its side.
|
||||
*Doesn't work with "stickysidebar".* Defaults to ``False``.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **externalrefs** (true or false): Display external links differently from
|
||||
internal links. Defaults to ``False``.
|
||||
|
||||
@ -1765,32 +1765,39 @@ macros and environments, see also :doc:`/latex`.
|
||||
It must be a list of tuples ``(startdocname, targetname, title, author,
|
||||
documentclass, toctree_only)``, where the items are:
|
||||
|
||||
* *startdocname*: document name that is the "root" of the LaTeX file. All
|
||||
documents referenced by it in TOC trees will be included in the LaTeX file
|
||||
too. (If you want only one LaTeX file, use your :confval:`master_doc`
|
||||
here.)
|
||||
* *targetname*: file name of the LaTeX file in the output directory.
|
||||
* *title*: LaTeX document title. Can be empty to use the title of the
|
||||
*startdoc*. This is inserted as LaTeX markup, so special characters like a
|
||||
*startdocname*
|
||||
String that specifies the :term:`document name` of the LaTeX file's master
|
||||
document. All documents referenced by the *startdoc* document in TOC trees
|
||||
will be included in the LaTeX file. (If you want to use the default master
|
||||
document for your LaTeX build, provide your :confval:`master_doc` here.)
|
||||
|
||||
*targetname*
|
||||
File name of the LaTeX file in the output directory.
|
||||
|
||||
*title*
|
||||
LaTeX document title. Can be empty to use the title of the *startdoc*
|
||||
document. This is inserted as LaTeX markup, so special characters like a
|
||||
backslash or ampersand must be represented by the proper LaTeX commands if
|
||||
they are to be inserted literally.
|
||||
* *author*: Author for the LaTeX document. The same LaTeX markup caveat as
|
||||
for *title* applies. Use ``\\and`` to separate multiple authors, as in:
|
||||
``'John \\and Sarah'`` (backslashes must be Python-escaped to reach
|
||||
LaTeX).
|
||||
* *documentclass*: Normally, one of ``'manual'`` or ``'howto'`` (provided
|
||||
by Sphinx and based on ``'report'``, resp. ``'article'``; Japanese
|
||||
documents use ``'jsbook'``, resp. ``'jreport'``.) "howto" (non-Japanese)
|
||||
documents will not get appendices. Also they have a simpler title page.
|
||||
Other document classes can be given. Independently of the document class,
|
||||
the "sphinx" package is always loaded in order to define Sphinx's custom
|
||||
LaTeX commands.
|
||||
|
||||
* *toctree_only*: Must be ``True`` or ``False``. If true, the *startdoc*
|
||||
document itself is not included in the output, only the documents
|
||||
referenced by it via TOC trees. With this option, you can put extra stuff
|
||||
in the master document that shows up in the HTML, but not the LaTeX
|
||||
output.
|
||||
*author*
|
||||
Author for the LaTeX document. The same LaTeX markup caveat as for *title*
|
||||
applies. Use ``\\and`` to separate multiple authors, as in:
|
||||
``'John \\and Sarah'`` (backslashes must be Python-escaped to reach LaTeX).
|
||||
|
||||
*documentclass*
|
||||
Normally, one of ``'manual'`` or ``'howto'`` (provided by Sphinx and based
|
||||
on ``'report'``, resp. ``'article'``; Japanese documents use ``'jsbook'``,
|
||||
resp. ``'jreport'``.) "howto" (non-Japanese) documents will not get
|
||||
appendices. Also they have a simpler title page. Other document classes
|
||||
can be given. Independently of the document class, the "sphinx" package is
|
||||
always loaded in order to define Sphinx's custom LaTeX commands.
|
||||
|
||||
*toctree_only*
|
||||
Must be ``True`` or ``False``. If true, the *startdoc* document itself is
|
||||
not included in the output, only the documents referenced by it via TOC
|
||||
trees. With this option, you can put extra stuff in the master document
|
||||
that shows up in the HTML, but not the LaTeX output.
|
||||
|
||||
.. versionadded:: 1.2
|
||||
In the past including your own document class required you to prepend the
|
||||
@ -2264,9 +2271,11 @@ These options influence manual page output.
|
||||
section)``, where the items are:
|
||||
|
||||
*startdocname*
|
||||
Document name that is the "root" of the manual page. All documents
|
||||
referenced by it in TOC trees will be included in the manual file too.
|
||||
(If you want one master manual page, use your :confval:`master_doc` here.)
|
||||
String that specifies the :term:`document name` of the manual page's master
|
||||
document. All documents referenced by the *startdoc* document in TOC trees
|
||||
will be included in the manual file. (If you want to use the default
|
||||
master document for your manual pages build, use your :confval:`master_doc`
|
||||
here.)
|
||||
|
||||
*name*
|
||||
Name of the manual page. This should be a short string without spaces or
|
||||
@ -2309,17 +2318,19 @@ These options influence Texinfo output.
|
||||
are:
|
||||
|
||||
*startdocname*
|
||||
Document name that is the "root" of the Texinfo file. All documents
|
||||
referenced by it in TOC trees will be included in the Texinfo file too.
|
||||
(If you want only one Texinfo file, use your :confval:`master_doc` here.)
|
||||
String that specifies the :term:`document name` of the the Texinfo file's
|
||||
master document. All documents referenced by the *startdoc* document in
|
||||
TOC trees will be included in the Texinfo file. (If you want to use the
|
||||
default master document for your Texinfo build, provide your
|
||||
:confval:`master_doc` here.)
|
||||
|
||||
*targetname*
|
||||
File name (no extension) of the Texinfo file in the output directory.
|
||||
|
||||
*title*
|
||||
Texinfo document title. Can be empty to use the title of the *startdoc*.
|
||||
Inserted as Texinfo markup, so special characters like ``@`` and ``{}``
|
||||
will need to be escaped to be inserted literally.
|
||||
Texinfo document title. Can be empty to use the title of the *startdoc*
|
||||
document. Inserted as Texinfo markup, so special characters like ``@`` and
|
||||
``{}`` will need to be escaped to be inserted literally.
|
||||
|
||||
*author*
|
||||
Author for the Texinfo document. Inserted as Texinfo markup. Use ``@*``
|
||||
@ -2488,12 +2499,21 @@ Options for the linkcheck builder
|
||||
|
||||
.. confval:: linkcheck_anchors_ignore
|
||||
|
||||
A list of regular expressions that match URIs that should skip checking
|
||||
the validity of anchors in links. This allows skipping entire sites, where
|
||||
anchors are used to control dynamic pages, or just specific anchors within
|
||||
a page, where JavaScript is used to add anchors dynamically, or use the
|
||||
fragment as part of to trigger an internal REST request. Default is
|
||||
``["/#!"]``.
|
||||
A list of regular expressions that match anchors Sphinx should skip when
|
||||
checking the validity of anchors in links. This allows skipping anchors that
|
||||
a website's JavaScript adds to control dynamic pages or when triggering an
|
||||
internal REST request. Default is ``["^!"]``.
|
||||
|
||||
.. note::
|
||||
|
||||
If you want to ignore anchors of a specific page or of pages that match a
|
||||
specific pattern (but still check occurrences of the same page(s) that
|
||||
don't have anchors), use :confval:`linkcheck_ignore` instead, for example
|
||||
as follows::
|
||||
|
||||
linkcheck_ignore = [
|
||||
'http://www.sphinx-doc.org/en/1.7/intro.html#'
|
||||
]
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
|
||||
@ -195,7 +195,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
|
||||
"""Collect section titles, their depth in the toc and the refuri."""
|
||||
# XXX: is there a better way than checking the attribute
|
||||
# toctree-l[1-8] on the parent node?
|
||||
if isinstance(doctree, nodes.reference) and 'refuri' in doctree:
|
||||
if isinstance(doctree, nodes.reference) and doctree.get('refuri'):
|
||||
refuri = doctree['refuri']
|
||||
if refuri.startswith('http://') or refuri.startswith('https://') \
|
||||
or refuri.startswith('irc:') or refuri.startswith('mailto:'):
|
||||
|
||||
@ -319,6 +319,7 @@ class BuildEnvironment(object):
|
||||
if docname in self.all_docs:
|
||||
self.all_docs.pop(docname, None)
|
||||
self.reread_always.discard(docname)
|
||||
self.included.discard(docname)
|
||||
|
||||
for version, changes in self.versionchanges.items():
|
||||
new = [change for change in changes if change[1] != docname]
|
||||
@ -339,6 +340,8 @@ class BuildEnvironment(object):
|
||||
self.all_docs[docname] = other.all_docs[docname]
|
||||
if docname in other.reread_always:
|
||||
self.reread_always.add(docname)
|
||||
if docname in other.included:
|
||||
self.included.add(docname)
|
||||
|
||||
for version, changes in other.versionchanges.items():
|
||||
self.versionchanges.setdefault(version, []).extend(
|
||||
|
||||
@ -1265,6 +1265,11 @@ class DataDocumenter(ModuleLevelDocumenter):
|
||||
# type: (bool) -> None
|
||||
pass
|
||||
|
||||
def get_real_modname(self):
|
||||
# type: () -> str
|
||||
return self.get_attr(self.parent or self.object, '__module__', None) \
|
||||
or self.modname
|
||||
|
||||
|
||||
class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type: ignore
|
||||
"""
|
||||
|
||||
@ -166,9 +166,22 @@ def import_object(modname, objpath, objtype='', attrgetter=safe_getattr, warning
|
||||
else:
|
||||
logger.debug('[autodoc] import %s', modname)
|
||||
|
||||
try:
|
||||
module = None
|
||||
objpath = list(objpath)
|
||||
while module is None:
|
||||
try:
|
||||
module = import_module(modname, warningiserror=warningiserror)
|
||||
logger.debug('[autodoc] => %r', module)
|
||||
logger.debug('[autodoc] import %s => %r', modname, module)
|
||||
except ImportError:
|
||||
logger.debug('[autodoc] import %s => failed', modname)
|
||||
if '.' in modname:
|
||||
# retry with parent module
|
||||
modname, name = modname.rsplit('.', 1)
|
||||
objpath.insert(0, name)
|
||||
else:
|
||||
raise
|
||||
|
||||
obj = module
|
||||
parent = None
|
||||
object_name = None
|
||||
|
||||
@ -43,7 +43,7 @@
|
||||
</div>
|
||||
<div class="sidebar">
|
||||
{%- block sidebartoc %}
|
||||
<h3>{{ _('Table Of Contents') }}</h3>
|
||||
<h3>{{ _('Table of Contents') }}</h3>
|
||||
{{ toctree() }}
|
||||
{%- endblock %}
|
||||
{%- block sidebarsearch %}
|
||||
|
||||
@ -7,5 +7,5 @@
|
||||
:copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
|
||||
:license: BSD, see LICENSE for details.
|
||||
#}
|
||||
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
|
||||
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table of Contents') }}</a></h3>
|
||||
{{ toctree() }}
|
||||
|
||||
@ -8,6 +8,6 @@
|
||||
:license: BSD, see LICENSE for details.
|
||||
#}
|
||||
{%- if display_toc %}
|
||||
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
|
||||
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table of Contents') }}</a></h3>
|
||||
{{ toc }}
|
||||
{%- endif %}
|
||||
|
||||
@ -9,9 +9,9 @@
|
||||
#}
|
||||
{%- extends "basic/layout.html" %}
|
||||
|
||||
{% if theme_collapsiblesidebar|tobool %}
|
||||
{%- block scripts %}
|
||||
{{ super() }}
|
||||
{% if theme_collapsiblesidebar|tobool %}
|
||||
<script type="text/javascript" src="{{ pathto('_static/sidebar.js', 1) }}"></script>
|
||||
{%- endblock %}
|
||||
{% endif %}
|
||||
{%- endblock %}
|
||||
|
||||
@ -54,7 +54,7 @@
|
||||
<div class="content">
|
||||
{#{%- if display_toc %}
|
||||
<div id="toc">
|
||||
<h3>{{ _('Table Of Contents') }}</h3>
|
||||
<h3>{{ _('Table of Contents') }}</h3>
|
||||
{{ toc }}
|
||||
</div>
|
||||
{%- endif %}#}
|
||||
|
||||
@ -38,7 +38,7 @@
|
||||
<div id="contentwrapper">
|
||||
{%- if display_toc %}
|
||||
<div id="toc" role="navigation" aria-label="table of contents navigation">
|
||||
<h3>{{ _('Table Of Contents') }}</h3>
|
||||
<h3>{{ _('Table of Contents') }}</h3>
|
||||
{{ toc }}
|
||||
</div>
|
||||
{%- endif %}
|
||||
|
||||
@ -9,3 +9,5 @@ Some additional anchors to exercise ignore code
|
||||
* `Example Bar invalid <http://example.com/#!bar>`_
|
||||
* `Example Bar invalid <http://example.com#!bar>`_ tests that default ignore anchor of #! does not need to be prefixed with /
|
||||
* `Example Bar invalid <http://example.com/#top>`_
|
||||
* `Example anchor invalid <http://www.sphinx-doc.org/en/1.7/intro.html#does-not-exist>`_
|
||||
* `Complete nonsense <https://localhost:7777/doesnotexist>`_
|
||||
|
||||
@ -771,6 +771,9 @@ def test_generate():
|
||||
('class', 'target.Outer.Inner'),
|
||||
('method', 'target.Outer.Inner.meth')],
|
||||
'class', 'Outer', all_members=True)
|
||||
assert_processes([('class', 'target.Outer.Inner'),
|
||||
('method', 'target.Outer.Inner.meth')],
|
||||
'class', 'target.Outer.Inner', all_members=True)
|
||||
|
||||
# test descriptor docstrings
|
||||
assert_result_contains(' Descriptor instance docstring.',
|
||||
|
||||
@ -21,14 +21,21 @@ def test_defaults(app, status, warning):
|
||||
content = (app.outdir / 'output.txt').text()
|
||||
|
||||
print(content)
|
||||
# looking for #top should fail
|
||||
# looking for '#top' and 'does-not-exist' not found should fail
|
||||
assert "Anchor 'top' not found" in content
|
||||
assert len(content.splitlines()) == 1
|
||||
assert "Anchor 'does-not-exist' not found" in content
|
||||
# looking for non-existent URL should fail
|
||||
assert " Max retries exceeded with url: /doesnotexist" in content
|
||||
assert len(content.splitlines()) == 3
|
||||
|
||||
|
||||
@pytest.mark.sphinx(
|
||||
'linkcheck', testroot='linkcheck', freshenv=True,
|
||||
confoverrides={'linkcheck_anchors_ignore': ["^!", "^top$"]})
|
||||
confoverrides={'linkcheck_anchors_ignore': ["^!", "^top$"],
|
||||
'linkcheck_ignore': [
|
||||
'https://localhost:7777/doesnotexist',
|
||||
'http://www.sphinx-doc.org/en/1.7/intro.html#']
|
||||
})
|
||||
def test_anchors_ignored(app, status, warning):
|
||||
app.builder.build_all()
|
||||
|
||||
|
||||
@ -124,7 +124,7 @@ def test_theme_sidebars(app, status, warning):
|
||||
|
||||
# test-theme specifies globaltoc and searchbox as default sidebars
|
||||
result = (app.outdir / 'index.html').text(encoding='utf8')
|
||||
assert '<h3><a href="#">Table Of Contents</a></h3>' in result
|
||||
assert '<h3><a href="#">Table of Contents</a></h3>' in result
|
||||
assert '<h3>Related Topics</h3>' not in result
|
||||
assert '<h3>This Page</h3>' not in result
|
||||
assert '<h3>Quick search</h3>' in result
|
||||
|
||||
Loading…
Reference in New Issue
Block a user