Merge branch '3.x'

CHANGES

@@ -38,6 +38,8 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #7477: imgconverter: Invoke "magick convert" command by default on Windows
+
 Deprecated
 ----------
 
@@ -53,6 +55,13 @@ Features added
 * C, added scope control directives, :rst:dir:`c:namespace`,
   :rst:dir:`c:namespace-push`, and :rst:dir:`c:namespace-pop`.
 * #7466: autosummary: headings in generated documents are not translated
+* #7481: html theme: Add right margin to footnote/citation labels
+* #7482: html theme: CSS spacing for code blocks with captions and line numbers
+* #7443: html theme: Add new options :confval:`globaltoc_collapse` and
+  :confval:`globaltoc_includehidden` to control the behavior of globaltoc in
+  sidebar
+* #7484: html theme: Avoid clashes between sidebar and other blocks
+* #7476: html theme: Relbar breadcrumb should contain current page
 
 Bugs fixed
 ----------
@@ -83,6 +92,7 @@ Bugs fixed
 
 * #7461: py domain: fails with IndexError for empty tuple in type annotation
 * #7461: autodoc: empty tuple in type annotation is not shown correctly
+* C++, fix spacing issue in east-const declarations.
 
 Testing
 --------

doc/_themes/sphinx13/layout.html

@@ -13,11 +13,6 @@
 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
 {% block sidebar2 %}{% endblock %}
 
-{% block linktags %}
-{{ super() }}
-    <link rel="canonical" href="http://www.sphinx-doc.org/en/master/{{ pagename }}{{ file_suffix }}" />
-{% endblock %}
-
 {% block extrahead %}
     <link href='https://fonts.googleapis.com/css?family=Open+Sans:300,400,700'
           rel='stylesheet' type='text/css' />

doc/conf.py

@@ -27,6 +27,7 @@ html_static_path = ['_static']
 html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
 html_additional_pages = {'index': 'index.html'}
 html_use_opensearch = 'http://sphinx-doc.org'
+html_baseurl = 'https://www.sphinx-doc.org/en/master/'
 
 htmlhelp_basename = 'Sphinxdoc'
 

doc/usage/extensions/imgconverter.rst

@@ -34,7 +34,19 @@ Configuration
    A path to :command:`convert` command.  By default, the imgconverter uses
    the command from search paths.
 
+   On windows platform, :command:`magick` command is used by default.
+
+   .. versionchanged:: 3.1
+
+      Use :command:`magick` command by default on windows
+
 .. confval:: image_converter_args
 
    Additional command-line arguments to give to :command:`convert`, as a list.
    The default is an empty list ``[]``.
+
+   On windows platform, it defaults to ``["convert"]``.
+
+   .. versionchanged:: 3.1
+
+      Use ``["convert"]`` by default on windows

doc/usage/theming.rst

@@ -155,6 +155,21 @@ These themes are:
     previous/next page using the keyboard's left and right arrows.  Defaults to
     ``False``.
 
+  - **globaltoc_collapse** (true or false): Only expand subsections
+    of the current document in ``globaltoc.html``
+    (see :confval:`html_sidebars`).
+    Defaults to ``True``.
+
+    .. versionadded:: 3.1
+
+  - **globaltoc_includehidden** (true or false): Show even those
+    subsections in ``globaltoc.html`` (see :confval:`html_sidebars`)
+    which have been included with the ``:hidden:`` flag of the
+    :rst:dir:`toctree` directive.
+    Defaults to ``False``.
+
+    .. versionadded:: 3.1
+
 **alabaster**
   `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
   (especially as used in his Requests project), which was itself originally

sphinx/domains/cpp.py

@@ -2062,12 +2062,15 @@ class ASTDeclSpecs(ASTBase):
         if self.trailingTypeSpec:
             if addSpace:
                 signode += nodes.Text(' ')
+            numChildren = len(signode)
             self.trailingTypeSpec.describe_signature(signode, mode, env,
                                                      symbol=symbol)
-            numChildren = len(signode)
-            self.rightSpecs.describe_signature(signode)
-            if len(signode) != numChildren:
-                signode += nodes.Text(' ')
+            addSpace = len(signode) != numChildren
+
+            if len(str(self.rightSpecs)) > 0:
+                if addSpace:
+                    signode += nodes.Text(' ')
+                self.rightSpecs.describe_signature(signode)
 
 
 # Declarator

sphinx/ext/autodoc/__init__.py

@@ -1754,9 +1754,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_autodocumenter(InstanceAttributeDocumenter)
     app.add_autodocumenter(SlotsAttributeDocumenter)
 
-    app.add_config_value('autoclass_content', 'class', True)
+    app.add_config_value('autoclass_content', 'class', True, ENUM('both', 'class', 'init'))
     app.add_config_value('autodoc_member_order', 'alphabetic', True)
-    app.add_config_value('autodoc_default_flags', [], True)
     app.add_config_value('autodoc_default_options', {}, True)
     app.add_config_value('autodoc_docstring_signature', True, True)
     app.add_config_value('autodoc_mock_imports', [], True)

sphinx/ext/imgconverter.py

@@ -9,6 +9,7 @@
 """
 
 import subprocess
+import sys
 from subprocess import CalledProcessError, PIPE
 from typing import Any, Dict
 
@@ -74,8 +75,17 @@ class ImagemagickConverter(ImageConverter):
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_post_transform(ImagemagickConverter)
-    app.add_config_value('image_converter', 'convert', 'env')
-    app.add_config_value('image_converter_args', [], 'env')
+    if sys.platform == 'win32':
+        # On Windows, we use Imagemagik v7 by default to avoid the trouble for
+        # convert.exe bundled with Windows.
+        app.add_config_value('image_converter', 'magick', 'env')
+        app.add_config_value('image_converter_args', ['convert'], 'env')
+    else:
+        # On other platform, we use Imagemagick v6 by default.  Especially,
+        # Debian/Ubuntu are still based of v6.  So we can't use "magick" command
+        # for these platforms.
+        app.add_config_value('image_converter', 'convert', 'env')
+        app.add_config_value('image_converter_args', [], 'env')
 
     return {
         'version': 'builtin',

sphinx/pycode/ast.py

@@ -9,7 +9,7 @@
 """
 
 import sys
-from typing import Dict, List, Type
+from typing import Dict, List, Type, Optional
 
 if sys.version_info > (3, 8):
     import ast
@@ -125,6 +125,17 @@ def unparse(node: ast.AST) -> str:
         raise NotImplementedError('Unable to parse %s object' % type(node).__name__)
 
 
+def _unparse_arg(arg: ast.arg, default: Optional[ast.AST]) -> str:
+    """Unparse a single argument to a string."""
+    name = unparse(arg)
+    if default:
+        if arg.annotation:
+            name += " = %s" % unparse(default)
+        else:
+            name += "=%s" % unparse(default)
+    return name
+
+
 def unparse_arguments(node: ast.arguments) -> str:
     """Unparse an arguments to string."""
     defaults = list(node.defaults)
@@ -143,25 +154,13 @@ def unparse_arguments(node: ast.arguments) -> str:
     args = []  # type: List[str]
     if hasattr(node, "posonlyargs"):  # for py38+
         for i, arg in enumerate(node.posonlyargs):  # type: ignore
-            name = unparse(arg)
-            if defaults[i]:
-                if arg.annotation:
-                    name += " = %s" % unparse(defaults[i])
-                else:
-                    name += "=%s" % unparse(defaults[i])
-            args.append(name)
+            args.append(_unparse_arg(arg, defaults[i]))
 
         if node.posonlyargs:  # type: ignore
             args.append('/')
 
     for i, arg in enumerate(node.args):
-        name = unparse(arg)
-        if defaults[i + posonlyargs]:
-            if arg.annotation:
-                name += " = %s" % unparse(defaults[i + posonlyargs])
-            else:
-                name += "=%s" % unparse(defaults[i + posonlyargs])
-        args.append(name)
+        args.append(_unparse_arg(arg, defaults[i + posonlyargs]))
 
     if node.vararg:
         args.append("*" + unparse(node.vararg))
@@ -169,13 +168,7 @@ def unparse_arguments(node: ast.arguments) -> str:
     if node.kwonlyargs and not node.vararg:
         args.append('*')
     for i, arg in enumerate(node.kwonlyargs):
-        name = unparse(arg)
-        if kw_defaults[i]:
-            if arg.annotation:
-                name += " = %s" % unparse(kw_defaults[i])
-            else:
-                name += "=%s" % unparse(kw_defaults[i])
-        args.append(name)
+        args.append(_unparse_arg(arg, kw_defaults[i]))
 
     if node.kwarg:
         args.append("**" + unparse(node.kwarg))

sphinx/themes/basic/globaltoc.html

@@ -8,4 +8,4 @@
     :license: BSD, see LICENSE for details.
 #}
 <h3><a href="{{ pathto(master_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
-{{ toctree() }}
+{{ toctree(includehidden=theme_globaltoc_includehidden, collapse=theme_globaltoc_collapse) }}

sphinx/themes/basic/layout.html

@@ -42,6 +42,7 @@
         {%- for parent in parents %}
           <li class="nav-item nav-item-{{ loop.index }}"><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>
         {%- endfor %}
+        <li class="nav-item nav-item-this"><a href="{{ link|e }}">{{ title }}</a></li>
         {%- block relbaritems %} {% endblock %}
       </ul>
     </div>

sphinx/themes/basic/static/basic.css_t

@@ -320,12 +320,17 @@ div.sidebar {
     background-color: #ffe;
     width: 40%;
     float: right;
+    clear: right;
 }
 
 p.sidebar-title {
     font-weight: bold;
 }
 
+div.admonition, div.topic, pre {
+    clear: both;
+}
+
 /* -- topics ---------------------------------------------------------------- */
 
 div.topic {
@@ -506,6 +511,7 @@ li > p:last-child {
 dl.footnote > dt,
 dl.citation > dt {
     float: left;
+    margin-right: 0.5em;
 }
 
 dl.footnote > dd,
@@ -645,21 +651,52 @@ span.pre {
 }
 
 td.linenos pre {
-    padding: 5px 0px;
     border: 0;
     background-color: transparent;
     color: #aaa;
 }
 
 table.highlighttable {
-    margin-left: 0.5em;
+    display: block;
+    margin: 1em 0;
+}
+
+table.highlighttable tbody {
+    display: block;
+}
+
+table.highlighttable tr {
+    display: flex;
 }
 
 table.highlighttable td {
-    padding: 0 0.5em 0 0.5em;
+    margin: 0;
+    padding: 0;
+}
+
+table.highlighttable td.linenos {
+    padding: 0 0.5em;
+}
+
+table.highlighttable td.code {
+    flex: 1;
+    overflow: hidden;
+}
+
+.highlight .hll {
+    display: block;
+}
+
+table.highlighttable pre {
+    margin: 0;
+}
+
+div.code-block-caption + div > table.highlighttable {
+    margin-top: 0;
 }
 
 div.code-block-caption {
+    margin-top: 1em;
     padding: 2px 5px;
     font-size: small;
 }
@@ -672,6 +709,7 @@ div.code-block-caption + div > div.highlight > pre {
     margin-top: 0;
 }
 
+table.highlighttable td.linenos,
 div.doctest > div.highlight span.gp {  /* gp: Generic.Prompt */
     user-select: none;
 }
@@ -685,11 +723,7 @@ div.code-block-caption span.caption-text {
 }
 
 div.literal-block-wrapper {
-    padding: 1em 1em 0;
-}
-
-div.literal-block-wrapper div.highlight {
-    margin: 0;
+    margin: 1em 0;
 }
 
 code.descname {

sphinx/themes/basic/theme.conf

@@ -10,3 +10,5 @@ sidebarwidth = 230
 body_min_width = 450
 body_max_width = 800
 navigation_with_keys = False
+globaltoc_collapse = true
+globaltoc_includehidden = false

tests/roots/test-ext-autodoc/target/__init__.py

@@ -145,6 +145,8 @@ First line of docstring
 
 
 class StrRepr(str):
+    """docstring"""
+
     def __repr__(self):
         return self