Skip to content

Commit

Permalink
Custom extensions (#45)
Browse files Browse the repository at this point in the history 
* minor fixups: spelling, pylint, & pkg.lock

* fix #26 (till sphinx v6.0)

* adding directives

Docs require sphinxcontrib-details-directive, and use it instead of sphinx-design dropdown directive. This also reverts the currently erroneous fix to #15.

Add `md-tab-set` & `md-tab-item` directives. Update docs with new page on how to use these new directives.

* monkey patch details directive

* pleasing pylint

* ran black on details_patch.py

* [no ci] remove dev artifact from docs

* introducing mermaid implementation

- updates docs about the details directive
- adds page that demonstrates how to use the md-mermaid directive.

* avoid unknown nodes.raw error revert conf.py a bit

* fix mermaid directive for pseudo latex output

* pylance's auto-import is annoying for typos

* fix html/latex output for mermaid diagrams

* cleaning it up a bit

* auto add directives that are tied to our CSS

* docs proofreading

* some simple review changes

* fix doc typos

* visit_tab_set is the transformer

* remove unused import

* use better pseudo latex output for mermaid graphs

* append input elements literally; use len(children)

* remove setting useless `set_id` attribute

* use SkipNode after rendering a tab set's divs

* remove artifact class

* 3rd round review changes
  • Loading branch information
@2bndy5
2bndy5 committed Mar 20, 2022
1 parent 8b83bf2 commit f925a44
Show file tree
Hide file tree
Showing 15 changed files with 748 additions and 152 deletions.
16 changes: 10 additions & 6 deletions docs/_static/extra_css.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 ****************************** */
Expand Down
109 changes: 33 additions & 76 deletions docs/admonitions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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``
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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>`_
3 changes: 1 addition & 2 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
143 changes: 143 additions & 0 deletions docs/content_tabs.rst
View file
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit f925a44

Please sign in to comment.