Custom extensions

docs/_static/extra_css.css

@@ -36,15 +36,19 @@
   mask-image: var(--md-admonition-icon--pied-piper);
 }
 
-/* *********************** sphinx-design tab-set style overrides ********************* */
+/* ************************ custom-tab-set-style **************************** */
 
-.sd-tab-set>input:checked+label {
-  border-color: var(--md-primary-fg-color);
-  color: var(--md-primary-fg-color);
+.custom-tab-set-style {
+  border: solid 2px var(--md-default-fg-color);
+  padding: 0 5px;
 }
 
-.sd-tab-set>input:not(:checked)+label:hover {
-  color: var(--md-primary-fg-color);
+/* *********************** custom-tab-item-style **************************** */
+
+.custom-tab-item-style {
+  border: solid 2px var(--md-default-fg-color);
+  padding: 0 5px;
+  margin-top: 3px;
 }
 
 /* ************************* inline icon stuff ****************************** */

docs/admonitions.rst

@@ -33,7 +33,7 @@ usage in other sphinx-based themes. They are:
 Admonitions from mkdocs-material
 ********************************
 
-Some addtional admonitions are supported via the source code from the mkdocs-material theme.
+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.
 
@@ -42,7 +42,7 @@ shown inside the demonstrated admonition.
 
 .. important::
    The ``: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
+   styling to work. Otherwise, the admonition will look like a `note` (as that is the
    default fallback style).
 
 ``todo``, ``info``
@@ -120,67 +120,48 @@ shown inside the demonstrated admonition.
          .. admonition:: Quote
             :class: quote
 
-Collapsable dropdown
+Collapsible dropdown
 *********************
 
-For collapsable dropdown admonitions, the mkdocs-material theme relies on a markdown syntax
-extension that cannot be used with sphinx. Instead, this sphinx-immaterial theme relies on
-other sphinx extensions to get similar (and more customizable) results.
-
-.. dropdown:: We endorse the sphinx-design extension!
-   :icon: package-dependents
-   :animate: fade-in-slide-down
-   :class-title: sd-text-primary sd-outline-primary
-   :class-container: sd-outline-danger
+.. _sphinxcontrib-details-directive extension: https://pypi.org/project/sphinxcontrib-details-directive
 
-   .. card:: You can do some pretty cool stuff with the :bdg-info-line:`sphinx-design extension`.
-      :class-title: sd-text-center
-      :margin: auto
-
-      .. grid::
+For collapsible dropdown admonitions, the mkdocs-material theme relies on a markdown syntax
+extension that cannot be used with sphinx. Instead, this sphinx-immaterial theme relies on
+the `sphinxcontrib-details-directive extension`_
+to get similar results.
 
-         .. grid-item::
-            :columns: auto
-            :margin: auto
+The `sphinxcontrib-details-directive extension`_ should be added to conf.py's extension list.
 
-            .. button-ref:: buttons
-               :color: success
+.. code-block:: python
 
-         .. grid-item::
-            :columns: auto
-            :margin: auto
+   extensions = ["sphinx_immaterial", "sphinxcontrib.details.directive"]
 
-            .. button-ref:: tabs
-               :color: success
 
-         .. grid-item::
-            :columns: auto
-            :margin: auto
+If the ``:class:`` option is not supplied to the ``details`` directive then the admonition
+style falls back to a `note` admonition style.
 
-            .. button-ref:: grids
-               :color: success
+.. details:: Open by default
+   :class: example
+   :open:
 
-         .. grid-item::
-            :columns: auto
-            :margin: auto
+   .. code-block:: rst
 
-            .. button-ref:: cards
-               :color: success
+      .. details:: Open by default
+         :class: example
+         :open:
 
-         .. grid-item::
-            :columns: auto
-            :margin: auto
+.. details:: Closed by default
+   :class: help
 
-            .. button-ref:: dropdowns
-               :color: success
+   .. code-block:: rst
 
-      Not to mention inline octicon :octicon:`infinity;1.5rem;sd-text-info` and fontawesome
-      :fab:`font-awesome-flag` icons and :bdg-ref-info:`badges`.
+      .. details:: Closed by default
+         :class: help
 
 Removing the title
 ******************
 
-Since the mkdocs-material theme relies on a mardown extension that also allows removing the title
+Since the mkdocs-material theme relies on a markdown extension that also allows removing the title
 from an admonition, this theme has an added directive to do just that: ``md-admonition``.
 
 The admonition's title can be removed if the ``md-admonition`` directive is not provided
@@ -222,10 +203,9 @@ If you want to add a custom admonition type, all you need is a color and an \*.s
 Copy the icon's code from the `.icons <https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons>`_
 folder and add the new CSS to an additional style sheet.
 
-.. tab-set::
+.. md-tab-set::
 
-   .. tab-item:: rST code
-      :class-label: sd-font-weight-light
+   .. md-tab-item:: rST code
 
       .. code-block:: rst
 
@@ -234,8 +214,7 @@ folder and add the new CSS to an additional style sheet.
 
                Don't tell him you use spaces instead of tabs...
 
-   .. tab-item:: CSS code
-      :class-label: sd-font-weight-light
+   .. md-tab-item:: CSS code
 
       .. code-block:: css
          :caption: docs/_static/extra_css.css
@@ -256,37 +235,15 @@ folder and add the new CSS to an additional style sheet.
                  mask-image: var(--md-admonition-icon--pied-piper);
          }
 
-   .. tab-item:: conf.py code
-      :class-label: sd-font-weight-light
+   .. md-tab-item:: conf.py code
 
-        .. code-block:: python
+      .. code-block:: python
 
-            html_static_path = ["_static"]
-            html_css_files = ["extra_css.css"]
+         html_static_path = ["_static"]
+         html_css_files = ["extra_css.css"]
 
 
 .. admonition:: Pied Piper
    :class: pied-piper
 
    Don't tell him you use spaces instead of tabs...
-
-.. _tabbed_locks:
-
-.. md-admonition::
-   :class: todo
-
-   The use of tabbed blocks (as seen above) are provided from `sphinx-design extension`_.
-   We added some custom CSS to make the tabs' labels conform to this theme's color palete.
-
-   .. code-block:: css
-
-      .sd-tab-set>input:checked+label {
-         border-color: var(--md-primary-fg-color);
-         color: var(--md-primary-fg-color);
-      }
-
-      .sd-tab-set>input:not(:checked)+label:hover {
-         color: var(--md-primary-fg-color);
-      }
-
-.. _sphinx-design extension: ` <https://sphinx-design.readthedocs.io/en/furo-theme>`_

docs/conf.py

@@ -34,13 +34,12 @@
     "sphinx.ext.todo",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
-    "sphinx_design",
+    "sphinxcontrib.details.directive",
 ]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "sphinx_docs": ("https://www.sphinx-doc.org/en/master", None),
-    "sphinx-design": ("https://sphinx-design.readthedocs.io/en/furo-theme", None),
 }
 
 # The reST default role (used for this markup: `text`) to use for all

docs/content_tabs.rst

@@ -0,0 +1,143 @@
+.. _sphinx-design tabs: https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html
+
+Content tabs
+============
+
+.. note::
+    This document discusses content tabs, not navigation tabs.
+
+Use of `content tabs in the mkdocs-material <https://squidfunk.github.io/mkdocs-material/reference/content-tabs/>`_
+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
+    only accepts children that are `md-tab-item` directives.
+
+    .. rst:directive:option:: class
+        :type: string
+
+        A space delimited list of qualified names that get used as the HTMl element's
+        ``class`` attribute.
+
+    .. rst:directive:option:: name
+        :type: string
+
+        A qualified name that get used as the HTML element's ``id`` attribute.
+
+        Use the `ref` role to reference the element by name.
+
+    This directive supports ``:class:`` and ``:name:`` options to use custom CSS classes
+    and reference links (respectively).
+
+    .. code-block:: rst
+
+        .. md-tab-set::
+            :class: custom-tab-set-style
+            :name: ref_this_tab_set
+
+            .. md-tab-item:: Local Ref
+
+                A reference to this tab set renders like so:
+                `tab set description <ref_this_tab_set>`.
+
+                This syntax can only be used on the same page as the tab set.
+
+            .. md-tab-item:: Cross-page Ref
+
+                To cross-reference this tab set from a different page, use
+                :ref:`tab set description <ref_this_tab_set>`
+
+                Clearly, this also works on the same page.
+
+            .. md-tab-item:: Custom CSS
+
+                .. literalinclude:: _static/extra_css.css
+                    :language: css
+                    :start-at: /* ************************ custom-tab-set-style
+                    :end-before: /* *********************** custom-tab-item-style
+
+    .. md-tab-set::
+        :class: custom-tab-set-style
+        :name: ref_this_tab_set
+
+        .. md-tab-item:: Local Ref
+
+            A reference to this tab set renders like so:
+            `tab set description <ref_this_tab_set>`.
+
+            This syntax can only be used on the same page as the tab set.
+
+        .. md-tab-item:: Cross-page Ref
+
+            To cross-reference this tab set from a different page, use
+            :ref:`tab set description <ref_this_tab_set>`
+
+            Clearly, this also works on the same page as the tab set.
+
+        .. md-tab-item:: Custom CSS
+
+            .. literalinclude:: _static/extra_css.css
+                :language: css
+                :start-at: /* ************************ custom-tab-set-style
+                :end-before: /* *********************** custom-tab-item-style
+
+.. rst:directive:: md-tab-item
+
+    This directive is used to create a tab within a set of content tabs. It requires a
+    label as it's argument. 
+
+    .. rst:directive:option:: class
+        :type: string
+
+        A space delimited list of qualified names that get used as the HTMl element's
+        ``class`` attribute.
+
+        Use the ``:class:`` option to optionally provide custom CSS classes to the tab's content
+        (not the tab's label).
+
+        .. code-block:: rst
+
+            .. md-tab-set::
+
+                .. md-tab-item:: Customized content
+                    :class: custom-tab-item-style
+
+                    This content could be styled differently from other page content.
+
+                .. md-tab-item:: Custom CSS
+
+                    .. literalinclude:: _static/extra_css.css
+                        :language: css
+                        :start-at: /* *********************** custom-tab-item-style
+                        :end-before: /* ************************* inline icon stuff
+
+        .. md-tab-set::
+
+            .. md-tab-item:: Customized content
+                :class: custom-tab-item-style
+
+                This content could be styled differently from other page content.
+
+            .. md-tab-item:: Custom CSS
+
+                .. literalinclude:: _static/extra_css.css
+                    :language: css
+                    :start-at: /* *********************** custom-tab-item-style
+                    :end-before: /* ************************* inline icon stuff
+
+Typical examples are seen in this documentations'
+`Custom admonitions <admonitions.html#custom-admonitions>`_ and
+:ref:`Version Information Structure <version_info_example>` sections.