Merge branch 'master' into refactor_highlighter

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

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

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

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
+   *startdocname*
-     documents referenced by it in TOC trees will be included in the LaTeX file
+     String that specifies the :term:`document name` of the LaTeX file's master
-     too.  (If you want only one LaTeX file, use your :confval:`master_doc`
+     document.  All documents referenced by the *startdoc* document in TOC trees
-     here.)
+     will be included in the LaTeX file.  (If you want to use the default master
-   * *targetname*: file name of the LaTeX file in the output directory.
+     document for your LaTeX build, provide your :confval:`master_doc` here.)
-   * *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
+   *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*
+   *author*
-     document itself is not included in the output, only the documents
+     Author for the LaTeX document.  The same LaTeX markup caveat as for *title*
-     referenced by it via TOC trees.  With this option, you can put extra stuff
+     applies.  Use ``\\and`` to separate multiple authors, as in:
-     in the master document that shows up in the HTML, but not the LaTeX
+     ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach LaTeX).
-     output.
+
+   *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
+     String that specifies the :term:`document name` of the manual page's master
-     referenced by it in TOC trees will be included in the manual file too.
+     document. All documents referenced by the *startdoc* document in TOC trees
-     (If you want one master manual page, use your :confval:`master_doc` here.)
+     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
+     String that specifies the :term:`document name` of the the Texinfo file's
-     referenced by it in TOC trees will be included in the Texinfo file too.
+     master document.  All documents referenced by the *startdoc* document in
-     (If you want only one Texinfo file, use your :confval:`master_doc` here.)
+     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*.
+     Texinfo document title.  Can be empty to use the title of the *startdoc*
-     Inserted as Texinfo markup, so special characters like ``@`` and ``{}``
+     document.  Inserted as Texinfo markup, so special characters like ``@`` and
-     will need to be escaped to be inserted literally.
+     ``{}`` 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
+   A list of regular expressions that match anchors Sphinx should skip when
-   the validity of anchors in links. This allows skipping entire sites, where
+   checking the validity of anchors in links. This allows skipping anchors that
-   anchors are used to control dynamic pages, or just specific anchors within
+   a website's JavaScript adds to control dynamic pages or when triggering an
-   a page, where JavaScript is used to add anchors dynamically, or use the
+   internal REST request. Default is ``["^!"]``.
-   fragment as part of to trigger 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
 

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:'):

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(

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

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)
+        module = None
-        logger.debug('[autodoc] => %r', module)
+        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

sphinx/themes/agogo/layout.html

@@ -43,7 +43,7 @@
         </div>
         <div class="sidebar">
           {%- block sidebartoc %}
-          <h3>{{ _('Table Of Contents') }}</h3>
+          <h3>{{ _('Table of Contents') }}</h3>
           {{ toctree() }}
           {%- endblock %}
           {%- block sidebarsearch %}

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.
 #}
-<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+<h3><a href="{{ pathto(master_doc) }}">{{ _('Table of Contents') }}</a></h3>
 {{ toctree() }}

sphinx/themes/basic/localtoc.html

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

sphinx/themes/classic/layout.html

@@ -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>
+    {% endif %}
 {%- endblock %}
-{% endif %}

sphinx/themes/haiku/layout.html

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

sphinx/themes/scrolls/layout.html

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

tests/roots/test-linkcheck/links.txt

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

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

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()
 

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