Merge upstream v8.5.6

.github/workflows/build.yml

@@ -19,24 +19,24 @@ jobs:
           - '16.x'
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         # Need full history to determine version number.
         fetch-depth: 0
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
-    - uses: actions/cache@v2
+    - uses: actions/cache@v3
       with:
         path: "**/node_modules"
         key: ${{ runner.os }}-${{ matrix.node-version }}-node_modules-${{ hashFiles('**/package-lock.json') }}
     - name: Setup Graphviz
-      uses: ts-graphviz/setup-graphviz@f1590cf4e989dd1429bff4fd6339e098050a1657 # v1
+      uses: ts-graphviz/setup-graphviz@79ea24a21263f792011acd62689c7ea2141feafa # v1.1.0
     - run: npm install
     - run: npm run check
     - name: Install Python packaging, linting, & testing tools
@@ -51,7 +51,7 @@ jobs:
     - name: Build wheel
       run: python setup.py sdist bdist_wheel
     - name: Upload wheels as artifacts
-      uses: actions/upload-artifact@v2
+      uses: actions/upload-artifact@v3
       if: ${{ matrix.python-version == '3.10' }}
       with:
         name: python-packages-${{ runner.os }}
@@ -74,7 +74,7 @@ jobs:
       run: sphinx-build -b latex . _build/latex -W --keep-going -T
     - name: Upload doc builds as artifacts
       if: ${{ matrix.python-version == '3.10' }}
-      uses: actions/upload-artifact@v2
+      uses: actions/upload-artifact@v3
       with:
         name: doc-builds-${{ runner.os }}
         path: docs/_build/
@@ -92,17 +92,17 @@ jobs:
       - build
     steps:
     - name: Download Linux package
-      uses: actions/download-artifact@v2
+      uses: actions/download-artifact@v3
       with:
         name: python-packages-Linux
         path: dist-Linux
     - name: Download macOS package
-      uses: actions/download-artifact@v2
+      uses: actions/download-artifact@v3
       with:
         name: python-packages-macOS
         path: dist-macOS
     - name: Download Windows package
-      uses: actions/download-artifact@v2
+      uses: actions/download-artifact@v3
       with:
         name: python-packages-Windows
         path: dist-Windows
@@ -123,7 +123,7 @@ jobs:
     needs:
       - build
     steps:
-    - uses: actions/download-artifact@v2
+    - uses: actions/download-artifact@v3
       with:
         name: python-packages-Linux
         path: dist

.stylelintrc

@@ -9,6 +9,7 @@
   ],
   "rules": {
     "alpha-value-notation": "number",
+    "annotation-no-unknown": null,
     "at-rule-empty-line-before": [
       "always",
       {

MKDOCS_MATERIAL_MERGE_BASE

@@ -1 +1 @@
-b8c994404750eb5cc64953a4e4eca06b839189dc
+f139b54c61b2df4512f15149cba2c222475e2bc9

docs/conf.py

@@ -106,6 +106,7 @@
 html_theme_options = {
     "icon": {
         "repo": "fontawesome/brands/github",
+        "edit": "material/file-edit-outline",
     },
     "site_url": "https://jbms.github.io/sphinx-immaterial/",
     "repo_url": "https://github.com/jbms/sphinx-immaterial/",
@@ -127,6 +128,7 @@
         "search.share",
         "toc.follow",
         "toc.sticky",
+        "content.tabs.link",
     ],
     "palette": [
         {

docs/content_tabs.rst

@@ -10,17 +10,6 @@ Use of `content tabs in the mkdocs-material <https://squidfunk.github.io/mkdocs-
 theme relies on a markdown extension that isn't used in the world of Sphinx. Instead,
 the sphinx-immaterial theme provides its own directives to make use of content tabs.
 
-.. admonition:: Linked Tabs
-    :class: missing
-
-    The `linked content tabs <https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs>`_
-    feature seen in mkdocs-material is not supported until that feature transitions from the mkdocs-material theme's insider
-    releases to its public releases.
-
-    You can use other sphinx extensions (like `sphinx-design tabs`_) to achieve this functionality.
-    However, other extensions will require some custom CSS styling to match the mkdocs-material
-    theme's styling for content tabs.
-
 .. rst:directive:: md-tab-set
 
     Each set of tabs on a page must begin with a `md-tab-set` directive. This directive
@@ -100,7 +89,80 @@ the sphinx-immaterial theme provides its own directives to make use of content t
                         :start-after: /* *********************** custom-tab-item-style
                         :end-before: /* ************************* inline icon stuff
 
+.. _linked_tabs:
+
+Linked tabs
+-----------
+
+Content tabs that share the same label can be selected synchronously by adding
+:python:`"content.tabs.link"` to the list of :themeconf:`features` in conf.py.
+
+.. code-block:: python
+    :caption: in conf.py
+
+    html_theme_options = {
+        "features": [
+            "content.tabs.link",
+        ],
+
+Include :python:`"navigation.instant"` in the list of :themeconf:`features` to have the
+synchronized selection persist across separate pages.
+
+.. important::
+    Linked content tabs must share the same **exact** label. Meaning, the argument given to the
+    :rst:dir:`md-tab-item` must be exactly the same (case sensitive) across all content tabs that
+    shall be synchronized.
+
+.. rst-example:: Linked content tabs example
+
+    .. md-tab-set::
+
+        .. md-tab-item:: Python
+
+            .. code-block:: python
+
+                def main():
+                    print("Hello world!")
+
+        .. md-tab-item:: C++
+
+            .. code-block:: cpp
+
+                #include <iostream>
+
+                int main(void) {
+                    std::cout << "Hello world!" << std::endl;
+                    return 0;
+                }
+
+
+    .. md-tab-set::
+
+        .. md-tab-item:: C only
+
+            .. code-block:: c
+
+                #include <stdio.h>
+
+                int main(void) {
+                    printf("Hello world!\n");
+                    return 0;
+                }
+
+        .. md-tab-item:: C++
+
+            .. code-block:: cpp
+
+                #include <iostream>
+
+                int main(void) {
+                    std::cout << "Hello world!" << std::endl;
+                    return 0;
+                }
+
+        .. md-tab-item:: Python
+
+            .. code-block:: python
 
-Typical examples are seen in this documentations'
-`Custom admonitions <admonitions.html#custom-admonitions>`_ and
-:ref:`Version Information Structure <version_info_example>` sections.
+                def main():
+                    print("Hello world!")

docs/customization.rst

@@ -210,32 +210,43 @@ Configuration Options
 
         Must be one of github, gitlab or bitbucket.
 
-    .. themeconf:: icon["repo"]
-
-        The icon that represents the source code repository can be changed using the ``repo`` field of the
-        ``icon`` `dict` (within the `html_theme_options` `dict`). Although this icon can be
-        `any of the icons bundled with this theme`_,
-        popular choices are:
-
-        - |fa-git| ``fontawesome/brands/git``
-        - |fa-git-alt| ``fontawesome/brands/git-alt``
-        - |fa-git-square| ``fontawesome/brands/git-square``
-        - |fa-github| ``fontawesome/brands/github``
-        - |fa-github-alt| ``fontawesome/brands/github-alt``
-        - |fa-github-square| ``fontawesome/brands/github-square``
-        - |fa-gitlab| ``fontawesome/brands/gitlab``
-        - |fa-gitkraken| ``fontawesome/brands/gitkraken``
-        - |fa-bitbucket| ``fontawesome/brands/bitbucket``
-
-        .. important::
-            This option has no effect if the :themeconf:`repo_url` option is not specified.
+    .. themeconf:: icon
 
         .. literalinclude:: conf.py
             :language: python
             :caption: This is the setting currently used by this documentation.
             :start-at: "icon": {
             :end-before: "site_url":
 
+        .. themeconf:: repo
+
+            The icon that represents the source code repository can be changed using the ``repo`` field of the
+            ``icon`` `dict` (within the `html_theme_options` `dict`). Although this icon can be
+            `any of the icons bundled with this theme`_,
+            popular choices are:
+
+            - |fa-git| ``fontawesome/brands/git``
+            - |fa-git-alt| ``fontawesome/brands/git-alt``
+            - |fa-git-square| ``fontawesome/brands/git-square``
+            - |fa-github| ``fontawesome/brands/github``
+            - |fa-github-alt| ``fontawesome/brands/github-alt``
+            - |fa-github-square| ``fontawesome/brands/github-square``
+            - |fa-gitlab| ``fontawesome/brands/gitlab``
+            - |fa-gitkraken| ``fontawesome/brands/gitkraken``
+            - |fa-bitbucket| ``fontawesome/brands/bitbucket``
+
+            .. important::
+                This option has no effect if the :themeconf:`repo_url` option is not specified.
+
+        .. themeconf:: edit
+
+            The icon used for the generated "edit this page" button at the top of the document.
+            This is only used if :themeconf:`edit_uri` is configured and when not explicitly hidden
+            using :themeconf:`hide-edit-link`.
+
+            As usual, `any of the icons bundled with this theme`_ can be used here. While the default is
+            ``material/pencil``, this documentation uses ``material/file-edit-outline``
+
     .. themeconf:: edit_uri
 
         This is the url segment that is concatenated with :themeconf:`repo_url` to point readers to the document's
@@ -250,6 +261,11 @@ Configuration Options
         of strings. The following features are supported:
 
         - `content.code.annotate <https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations>`_
+        - `content.tabs.link <https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs>`_
+
+          .. seealso::
+              Please refer to the :ref:`linked_tabs` section for more information.
+
         - `header.autohide <https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#automatic-hiding>`_
         - `navigation.expand <https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-expansion>`_
         - `navigation.instant <https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-loading>`_

merge_from_mkdocs_material.py

@@ -45,7 +45,7 @@
     # Generated files
     "material",
     # mkdocs-specific files
-    "src/*.py",
+    "src/**/*.py",
     "src/mkdocs_theme.yml",
     "src/404.html",
     "mkdocs.yml",
@@ -63,6 +63,7 @@
     "package-lock.json",
     "*.md",
     "giscus.json",
+    "pyproject.toml",
 ]
 
 ap = argparse.ArgumentParser()
@@ -151,8 +152,13 @@ def _create_adjusted_tree(ref: str, temp_workdir: str) -> str:
         cwd=clone_dir,
         check=True,
     )
+    exclude = []
+    # filter out exclude patterns for paths that don't exist in the temp_workdir
+    for pattern in MKDOCS_EXCLUDE_PATTERNS:
+        for file in pathlib.Path(temp_workdir).rglob(pattern):
+            exclude.append(str(file))
     subprocess.run(
-        ["git", "rm", "--quiet", "-r"] + MKDOCS_EXCLUDE_PATTERNS,
+        ["git", "rm", "--quiet", "-r"] + exclude,
         cwd=temp_workdir,
         check=True,
         stdout=subprocess.PIPE,
@@ -205,6 +211,8 @@ def _characterize_git_status(file_status):
             continue
         if status != "  ":
             updated.append(filename)
+        else:
+            print(filename, "has unexpected status", repr(status))
     return updated, conflicts
 
 
@@ -301,8 +309,13 @@ def main():
             subprocess.run(
                 ["patch", "-p1"], stdin=std_in_file, check=True, cwd=script_dir
             )
-        print("\nStaging non-conflicting files.")
-        subprocess.run(["git", "add", "--"] + updated_files, check=True, cwd=script_dir)
+        if updated_files:
+            print("\nStaging non-conflicting files.")
+            subprocess.run(
+                ["git", "add", "--"] + updated_files, check=True, cwd=script_dir
+            )
+        else:
+            print("There are no files to update.")
         pathlib.Path(merge_base_path).write_text(
             resolved_source_ref + "\n", encoding="utf-8"
         )