diff --git a/AUTHORS b/AUTHORS index 8fd867481..1cbb20137 100644 --- a/AUTHORS +++ b/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 diff --git a/CHANGES b/CHANGES index 1efe974fb..1c07f7e18 100644 --- a/CHANGES +++ b/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 -------- diff --git a/doc/theming.rst b/doc/theming.rst index fccc2362e..3308fe632 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -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``. diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 7364cbadc..dd6fcfaef 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -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 diff --git a/sphinx/builders/_epub_base.py b/sphinx/builders/_epub_base.py index 2a975fa94..eaab43fda 100644 --- a/sphinx/builders/_epub_base.py +++ b/sphinx/builders/_epub_base.py @@ -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:'): diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index fcc99b7cd..20ff9e336 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -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( diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 62143fda4..4a9b59537 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -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 """ diff --git a/sphinx/ext/autodoc/importer.py b/sphinx/ext/autodoc/importer.py index 20d448506..4b92a7b59 100644 --- a/sphinx/ext/autodoc/importer.py +++ b/sphinx/ext/autodoc/importer.py @@ -167,8 +167,21 @@ def import_object(modname, objpath, objtype='', attrgetter=safe_getattr, warning logger.debug('[autodoc] import %s', modname) try: - module = import_module(modname, warningiserror=warningiserror) - logger.debug('[autodoc] => %r', module) + module = None + objpath = list(objpath) + while module is None: + try: + module = import_module(modname, warningiserror=warningiserror) + 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 diff --git a/sphinx/themes/agogo/layout.html b/sphinx/themes/agogo/layout.html index 8bd476cad..f2c880537 100644 --- a/sphinx/themes/agogo/layout.html +++ b/sphinx/themes/agogo/layout.html @@ -43,7 +43,7 @@
{%- block sidebartoc %} -

{{ _('Table Of Contents') }}

+

{{ _('Table of Contents') }}

{{ toctree() }} {%- endblock %} {%- block sidebarsearch %} diff --git a/sphinx/themes/basic/globaltoc.html b/sphinx/themes/basic/globaltoc.html index dc6fea373..7671a93ca 100644 --- a/sphinx/themes/basic/globaltoc.html +++ b/sphinx/themes/basic/globaltoc.html @@ -7,5 +7,5 @@ :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. #} -

{{ _('Table Of Contents') }}

+

{{ _('Table of Contents') }}

{{ toctree() }} diff --git a/sphinx/themes/basic/localtoc.html b/sphinx/themes/basic/localtoc.html index 5d3c7f4fd..d4cc9e31d 100644 --- a/sphinx/themes/basic/localtoc.html +++ b/sphinx/themes/basic/localtoc.html @@ -8,6 +8,6 @@ :license: BSD, see LICENSE for details. #} {%- if display_toc %} -

{{ _('Table Of Contents') }}

+

{{ _('Table of Contents') }}

{{ toc }} {%- endif %} diff --git a/sphinx/themes/classic/layout.html b/sphinx/themes/classic/layout.html index 8042e3f7e..bee2ffd1e 100644 --- a/sphinx/themes/classic/layout.html +++ b/sphinx/themes/classic/layout.html @@ -9,9 +9,9 @@ #} {%- extends "basic/layout.html" %} -{% if theme_collapsiblesidebar|tobool %} {%- block scripts %} {{ super() }} + {% if theme_collapsiblesidebar|tobool %} + {% endif %} {%- endblock %} -{% endif %} diff --git a/sphinx/themes/haiku/layout.html b/sphinx/themes/haiku/layout.html index c93c52dbd..c3c79c4d6 100644 --- a/sphinx/themes/haiku/layout.html +++ b/sphinx/themes/haiku/layout.html @@ -54,7 +54,7 @@
{#{%- if display_toc %}
-

{{ _('Table Of Contents') }}

+

{{ _('Table of Contents') }}

{{ toc }}
{%- endif %}#} diff --git a/sphinx/themes/scrolls/layout.html b/sphinx/themes/scrolls/layout.html index 7bb7b19e3..0f9232a00 100644 --- a/sphinx/themes/scrolls/layout.html +++ b/sphinx/themes/scrolls/layout.html @@ -38,7 +38,7 @@
{%- if display_toc %} {%- endif %} diff --git a/tests/roots/test-linkcheck/links.txt b/tests/roots/test-linkcheck/links.txt index 36376bef4..d5057e08e 100644 --- a/tests/roots/test-linkcheck/links.txt +++ b/tests/roots/test-linkcheck/links.txt @@ -9,3 +9,5 @@ Some additional anchors to exercise ignore code * `Example Bar invalid `_ * `Example Bar invalid `_ tests that default ignore anchor of #! does not need to be prefixed with / * `Example Bar invalid `_ +* `Example anchor invalid `_ +* `Complete nonsense `_ diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 53d8a1e14..a42210a4c 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -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.', diff --git a/tests/test_build_linkcheck.py b/tests/test_build_linkcheck.py index 839a15628..1716a0c42 100644 --- a/tests/test_build_linkcheck.py +++ b/tests/test_build_linkcheck.py @@ -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() diff --git a/tests/test_theming.py b/tests/test_theming.py index 8c09271e3..43e97473d 100644 --- a/tests/test_theming.py +++ b/tests/test_theming.py @@ -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 '

Table Of Contents

' in result + assert '

Table of Contents

' in result assert '

Related Topics

' not in result assert '

This Page

' not in result assert '

Quick search

' in result