Skip to content

Commit

Permalink
Merge upstream v8.5.6 (#171)
Browse files Browse the repository at this point in the history 
* update merge script for missing files in git index
* updates from upstream v8.5.6
* update official github action versions in CI
* resolve #61
    - enables linked content tabs and explains/demos how to use them in docs
* document how to change the "edit this pg" icon
* document changing admonition icons
* doc announce block & use announce.dismiss feature
* doc user feedback feature
* allow use of consent popup (no docs for it though)
* revert metadata keys' name changes
    - approved workaround to sphinx-doc/sphinx#10932 is to
      use a blank line at start of doc before metadata
  • Loading branch information
@2bndy5
2bndy5 committed Oct 24, 2022
1 parent a944f27 commit eedce14
Show file tree
Hide file tree
Showing 128 changed files with 5,963 additions and 3,082 deletions.
22 changes: 11 additions & 11 deletions .github/workflows/build.yml
View file
Expand Up @@ -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
Expand All @@ -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 }}
Expand All @@ -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/
Expand All @@ -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
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions .stylelintrc
View file
Expand Up @@ -9,6 +9,7 @@
],
"rules": {
"alpha-value-notation": "number",
"annotation-no-unknown": null,
"at-rule-empty-line-before": [
"always",
{
Expand Down
2 changes: 1 addition & 1 deletion MKDOCS_MATERIAL_MERGE_BASE
View file
@@ -1 +1 @@
b8c994404750eb5cc64953a4e4eca06b839189dc
f139b54c61b2df4512f15149cba2c222475e2bc9
8 changes: 8 additions & 0 deletions docs/_templates/base.html
View file
@@ -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 %}
140 changes: 110 additions & 30 deletions docs/admonitions.rst
View file
Expand Up @@ -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
**************
Expand All @@ -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
Expand All @@ -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::
Expand All @@ -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
******************
Expand All @@ -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
Expand Down Expand Up @@ -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",
},
},
}

0 comments on commit eedce14

Please sign in to comment.