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/_templates/base.html

@@ -0,0 +1,8 @@
+{% extends "!base.html" %}
+{% block announce %}
+  <p>
+    Now includes
+    <a href="https://squidfunk.github.io/mkdocs-material/changelog/">changes from mkdocs-material theme</a>
+    v8.5.6
+  </p>
+{% endblock %}

docs/admonitions.rst

@@ -2,7 +2,7 @@
 Admonitions
 ===========
 
-The theme uses the ``admonition`` directives for Sphinx admonitions.
+This theme uses the :dutree:`admonition` directives for Sphinx admonitions.
 
 rST and Sphinx
 **************
@@ -14,92 +14,92 @@ usage in other sphinx-based themes. They are:
 .. rst-example:: ``note``, ``todo``, ``seealso``
 
    .. seealso::
-      This admonition is specific to Sphinx directives and not defined in the rST specifications
-      as you can `seealso`.
+      This admonition is specific to Sphinx directives and not defined in the reStructuredText
+      specifications as you can `seealso`. The `todo` admonition is also defined by Sphinx.
 
-      ``note`` and ``todo`` are admonitions defined by the rST specifications.
+      The :dutree:`note` admonition *is* defined by the reStructuredText specifications.
 
 .. rst-example:: ``tip``, ``hint``, ``important``
 
    .. important::
-      It is **important** to correctly use admonitions.
+      It is :dutree:`important` to correctly use admonitions.
 
 .. rst-example:: ``attention``, ``caution``, ``warning``
 
    .. warning::
-      This is a **warning**.
+      This is a :dutree:`warning`.
 
 .. rst-example:: ``danger``, ``error``
 
    .. error::
-      You have made a grave **error**.
+      You have made a grave :dutree:`error`.
 
 Admonitions from mkdocs-material
 ********************************
 
 Some additional admonitions are supported via the source code from the mkdocs-material theme.
 These admonitions can still be used, but the syntax is a little different because it relies
-on the generic admonition defined in the reStructuredText specifications.
+on the generic :dutree:`admonition` defined in the reStructuredText specifications.
 
 To use the following admonitions' styles from the mkdocs-material theme, the rST syntax is
-shown to demonstrate using the ``:class:`` option of generic admonitions.
+shown to demonstrate using the :rst:`:class:` option of generic admonitions.
 
 .. important::
-   The ``:class:`` options below (in the rST code blocks) must use lower case letters for the
+   The :rst:`:class:` options below (in the rST code blocks) must use lower case letters for the
    styling to work. Otherwise, the admonition will look like a `note` (as that is the
    default fallback style).
 
-.. rst-example:: ``todo``, ``info``
+.. rst-example:: :css:`todo`, :css:`info`
 
    .. admonition:: Info
       :class: info
 
-      Thanks to the mkdocs-material theme, the ``todo`` class is also an alias of the
-      ``info`` class when not using the `.. todo:: <todo>` directive.
+      Thanks to the mkdocs-material theme, the :css:`todo` class is also an alias of
+      the :css:`info` class when not using the `todo` directive.
 
-.. rst-example:: ``abstract``, ``summary``, ``tldr``
+.. rst-example:: :css:`abstract`, :css:`summary`, :css:`tldr`
 
    .. admonition:: TL;DR
       :class: tldr
 
-      The ``:class: tldr`` part is important.
+      The :rst:`:class: tldr` part is important.
 
-.. rst-example:: ``success``, ``check``, ``done``
+.. rst-example:: :css:`success`, :css:`check`, :css:`done`
 
    .. admonition:: Accomplished
       :class: done
 
-      This style is used for ``success``, ``check``, ``done`` CSS classes.
+      This style is used for :css:`success`, :css:`check`, :css:`done` CSS classes.
 
-.. rst-example:: ``question``, ``help``, ``faq``
+.. rst-example:: :css:`question`, :css:`help`, :css:`faq`
 
    .. admonition:: FAQ
       :class: faq
 
       Helpful advice goes here.
 
-.. rst-example:: ``failure``, ``fail``, ``missing``
+.. rst-example:: :css:`failure`, :css:`fail`, :css:`missing`
 
    .. admonition:: Something Missing
       :class: missing
 
       We expected some loss of feature-coverage.
 
-.. rst-example:: ``bug``
+.. rst-example:: :css:`bug`
 
    .. admonition:: Known Bug
       :class: bug
 
       Bug reported data/conclusion.
 
-.. rst-example:: ``example``
+.. rst-example:: :css:`example`
 
    .. admonition:: Example Admonition
       :class: example
 
       Example Body.
 
-.. rst-example:: ``cite``, ``quote``
+.. rst-example:: :css:`cite`, :css:`quote`
 
    .. admonition:: Unknown Quote
       :class: quote
@@ -122,7 +122,7 @@ The `sphinxcontrib-details-directive extension`_ should be added to conf.py's ex
 
    extensions = ["sphinx_immaterial", "sphinxcontrib.details.directive"]
 
-If the ``:class:`` option is not supplied to the ``details`` directive then the admonition
+If the :rst:`:class:` option is not supplied to the ``details`` directive then the admonition
 style falls back to a `note` admonition style.
 
 .. rst-example::
@@ -131,14 +131,14 @@ style falls back to a `note` admonition style.
       :class: example
       :open:
 
-      Use the ``:open:`` option as a flag to expand the admonition by default.
+      Use the :rst:`:open:` option as a flag to expand the admonition by default.
 
 .. rst-example::
 
    .. details:: Closed by default
       :class: help
 
-      Without the ``:open:`` flag, the admonition is collapsed by default.
+      Without the :rst:`:open:` flag, the admonition is collapsed by default.
 
 Removing the title
 ******************
@@ -148,25 +148,25 @@ from an admonition, this theme has an added directive to do just that: ``md-admo
 
 The admonition's title can be removed if the ``md-admonition`` directive is not provided
 any arguments. Because the ``md-admonition`` directive is an adaptation of the generic
-``admonition`` directive, the ``class`` option is still respected.
+:dutree:`admonition` directive, the :rst:`:class:` option is still respected.
 
 .. rst-example::
 
    .. md-admonition::
       :class: error
 
-      This example uses the styling of the ``error`` admonition
+      This example uses the styling of the :css:`error` admonition
 
 .. rst-example::
 
    .. md-admonition:: Using a title
       :class: help
 
-      This example uses the styling of the ``help`` admonition
+      This example uses the styling of the :css:`help` admonition
 
 .. hint::
-   You can use the ``md-admonition`` directive in other themes by adding the theme's module to your
-   ``extensions`` list in *conf.py*
+   You can use the ``md-admonition`` directive in other Sphinx themes by adding the theme's module to
+   your `extensions` list in *conf.py*
 
    .. code-block:: python
 
@@ -206,3 +206,83 @@ folder and add the new CSS to an additional style sheet.
 
          html_static_path = ["_static"]
          html_css_files = ["extra_css.css"]
+
+.. _change_admonition_icon:
+
+Changing the Admonition Icon
+----------------------------
+
+Any of the above builtin admonitions' icons can be changed using the
+:themeconf:`icon`\ [:themeconf:`admonition`] field in :confval:`html_theme_options` settings.
+
+.. code-block:: python
+   :caption: Changing the `note` icon in conf.py
+
+   html_theme_options = {
+       "icon": {
+           "admonition": {
+               "note": "material/file-document-outline",
+           },
+       },
+   }
+
+.. admonition:: ``seealso`` uses the ``note`` icon
+   :class: missing
+
+   The `seealso` admonition (which is specific to Sphinx - not reStructuredText) will use the same
+   icon set for the `note` admonition. If you want to override the icon for the `seealso`
+   admonition, then use the tactic shown in the `Custom admonitions`_ section (with regard to
+   only the icon changes in CSS).
+
+.. details:: Alternate icon sets
+   :class: example
+
+   Here's some recipes for use in conf.py
+
+   .. md-tab-set::
+
+      .. md-tab-item:: Octicons
+
+         .. code-block:: python
+
+            html_theme_options = {
+                "icon": {
+                    "admonition": {
+                        "note": "octicons/tag-16",
+                        "abstract": "octicons/checklist-16",
+                        "info": "octicons/info-16",
+                        "tip": "octicons/squirrel-16",
+                        "success": "octicons/check-16",
+                        "question": "octicons/question-16",
+                        "warning": "octicons/alert-16",
+                        "failure": "octicons/x-circle-16",
+                        "danger": "octicons/zap-16",
+                        "bug": "octicons/bug-16",
+                        "example": "octicons/beaker-16",
+                        "quote": "octicons/quote-16",
+                    },
+                },
+            }
+
+      .. md-tab-item:: FontAwesome
+
+         .. code-block:: python
+
+            html_theme_options = {
+                "icon": {
+                    "admonition": {
+                        "note": "fontawesome/solid/note-sticky",
+                        "abstract": "fontawesome/solid/book",
+                        "info": "fontawesome/solid/circle-info",
+                        "tip": "fontawesome/solid/bullhorn",
+                        "success": "fontawesome/solid/check",
+                        "question": "fontawesome/solid/circle-question",
+                        "warning": "fontawesome/solid/triangle-exclamation",
+                        "failure": "fontawesome/solid/bomb",
+                        "danger": "fontawesome/solid/skull",
+                        "bug": "fontawesome/solid/robot",
+                        "example": "fontawesome/solid/flask",
+                        "quote": "fontawesome/solid/quote-left",
+                    },
+                },
+            }