Add Sphinx directive/roles: "infocard" and "tag(s)"

A composite component offering a title, description text, and both
verbose and short tags. It is suitable for authoring pages enumerating
items with dense information, without the maintenance nightmares of
tables.

References:
- https://hiveeyes.org/docs/arduino/firmware/overview.html
- https://kotori.readthedocs.io/en/latest/integration/

Author: amotl

docs/get_started.md

@@ -63,6 +63,8 @@ Head over to the "directives" and "roles" sections to learn about the web elemen
 provided by this collection, and how to use them in your documentation markup.
 
 - [](#gridtable-directive)
+- [](#infocard-directive)
+- [](#tag-role)
 
 Both [reStructuredText] and [Markedly Structured Text] syntax are supported equally well.
 

docs/index.md

@@ -70,6 +70,14 @@ get_started
 :hidden:
 
 gridtable
+infocard
+```
+
+```{toctree}
+:caption: Roles
+:hidden:
+
+tag
 ```
 
 ```{toctree}
@@ -93,6 +101,20 @@ sandbox
 HTML table based on a grid layout, with ergonomic top-down configuration.
 :::
 
+:::{grid-item-card} {octicon}`note` Info card
+:link: infocard
+:link-type: doc
+
+Composite info card container element, to be used as a grid item.
+:::
+
+:::{grid-item-card} {octicon}`plus-circle` Special badges
+:link: tag
+:link-type: doc
+
+Special {bdg-primary}`badges` and other components.
+:::
+
 ::::
 
 -----------

docs/infocard.md

@@ -0,0 +1,64 @@
+(infocard-directive)=
+
+# Info Card
+
+
+## About
+
+A composite info card container element, to be used as an item within
+a [grid layout](inv:sd#grids). It provides the Sphinx directive `info-card`.
+
+
+## Details
+
+The info card is a composite element offering a title, description text, and
+both verbose and short tags. It is suitable for authoring pages enumerating
+items with dense information, without the maintenance nightmares of tables.
+
+For a compact notation of the short tag elements, it uses the corresponding
+[](#tag-role) for efficiently rendering [](inv:sd#badges), which is also
+provided by this package.
+
+
+## Synopsis
+
+::::{info-card}
+
+:::{grid-item}
+:columns: 8
+[example.org/beagles](https://example.org/beagles)
+
+A module for collecting votes from beagles, \
+and for consolidating them.
+
+**Author:** C. Schultz, Universal Features Syndicate \
+**Contact:** Los Angeles, CA; <cschultz@peanuts.example.org>
+:::
+
+:::{grid-item}
+:columns: 4
+
+{tags-primary}`foo, bar`
+
+{tags-success}`baz`
+
+{tags-secondary}`qux`
+
+{tags-info}`anything`
+:::
+
+::::
+
+
+## Usage
+````{tab-set-code}
+```{literalinclude} ./snippets/myst/infocard.md
+:language: markdown
+```
+```{literalinclude} ./snippets/rst/infocard.rst
+:language: rst
+```
+````
+
+
+_This page is written in Markedly Structured Text (MyST Markdown)._

docs/snippets/myst/infocard.md

@@ -0,0 +1,26 @@
+::::{info-card}
+
+:::{grid-item}
+:columns: 8
+[example.org/beagles](https://example.org/beagles)
+
+A module for collecting votes from beagles, \
+and for consolidating them.
+
+**Author:** C. Schultz, Universal Features Syndicate \
+**Contact:** Los Angeles, CA; <cschultz@peanuts.example.org>
+:::
+
+:::{grid-item}
+:columns: 4
+
+{tags-primary}`foo, bar`
+
+{tags-success}`baz`
+
+{tags-secondary}`qux`
+
+{tags-info}`anything`
+:::
+
+::::

docs/snippets/myst/tag.md

@@ -0,0 +1,2 @@
+{tag}`foo, bar`
+{tags}`foo, bar`

docs/snippets/rst/infocard.rst

@@ -0,0 +1,23 @@
+.. info-card::
+
+    .. grid-item::
+        :columns: 8
+
+        `example.org/beagles <https://example.org/beagles>`_
+
+        | A module for collecting votes from beagles,
+        | and for consolidating them.
+
+        | **Author:** C. Schultz, Universal Features Syndicate
+        | **Contact:** Los Angeles, CA; <cschultz@peanuts.example.org>
+
+    .. grid-item::
+        :columns: 4
+
+        :tags-primary:`foo, bar`
+
+        :tags-success:`baz`
+
+        :tags-secondary:`qux`
+
+        :tags-info:`anything`

docs/snippets/rst/tag.rst

@@ -0,0 +1,2 @@
+:tag:`foo, bar`
+:tags:`foo, bar`

docs/tag.md

@@ -0,0 +1,170 @@
+(tag-role)=
+
+# `tag(s)` role
+
+
+## About
+
+The `tag` and `tags` roles are shortcuts to the `badge` roles of sphinx{design},
+see [](inv:sd#badges).
+
+
+## Details
+
+The idea is to need less code for defining "tag"-like badges within the
+[](#infocard-directive) element. All of them will use the `outline` option flag
+by default, to give them a corresponding visual appearance.
+
+
+## Synopsis
+
+There is the `{tag}`, and the `{tags}` role. A `{tag}` will render its text content
+1:1 into a single badge element, while `{tags}` will split the text by comma (`,`),
+and renders the outcome using individual badge elements.
+
+
+::::{sd-table}
+:widths: 3 3 3 3
+:row-class: top-border
+
+:::{sd-row}
+```{sd-item} **Description**
+```
+```{sd-item} **Appearance**
+```
+```{sd-item} **MyST syntax**
+```
+```{sd-item} **rST syntax**
+```
+:::
+
+:::{sd-row}
+```{sd-item} Single tag
+```
+```{sd-item}
+{tag}`foo, bar`
+```
+```{sd-item}
+```markdown
+{tag}`foo, bar`
+```
+```{sd-item}
+```restructuredtext
+:tag:`foo, bar`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Multiple tags
+```
+```{sd-item}
+{tags}`foo, bar`
+```
+```{sd-item}
+```markdown
+{tags}`foo, bar`
+```
+```{sd-item}
+```restructuredtext
+:tags:`foo, bar`
+```
+:::
+
+::::
+
+
+## Color variants
+
+All colors of badges are supported, by appending a color label from the list of
+[semantic colors] as a suffix to the role name, like presented below.
+
+::::{sd-table}
+:widths: 3 3 6
+:row-class: top-border
+
+:::{sd-row}
+```{sd-item} **Description**
+```
+```{sd-item} **Appearance**
+```
+```{sd-item} **MyST syntax**
+```
+:::
+
+:::{sd-row}
+```{sd-item} Primary and secondary
+```
+```{sd-item}
+{tags-primary}`foo, bar` \
+{tags-secondary}`foo, bar`
+```
+```{sd-item}
+```markdown
+{tags-primary}`foo, bar` \
+{tags-secondary}`foo, bar`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Admonitions
+```
+```{sd-item}
+{tags-success}`foo, bar` \
+{tags-info}`foo, bar` \
+{tags-warning}`foo, bar` \
+{tags-danger}`foo, bar`
+```
+```{sd-item}
+```markdown
+{tags-success}`foo, bar` \
+{tags-info}`foo, bar` \
+{tags-warning}`foo, bar` \
+{tags-danger}`foo, bar`
+```
+:::
+
+:::{sd-row}
+```{sd-item}
+Light to dark
+```
+```{sd-item}
+{tags-white}`foo, bar` \
+{tags-light}`foo, bar` \
+{tags-muted}`foo, bar` \
+{tags-dark}`foo, bar` \
+{tags-black}`foo, bar`
+```
+```{sd-item}
+```markdown
+{tags-white}`foo, bar` \
+{tags-light}`foo, bar` \
+{tags-muted}`foo, bar` \
+{tags-dark}`foo, bar` \
+{tags-black}`foo, bar`
+```
+:::
+
+::::
+
+````{note}
+While the table above only presents Markdown syntax, reStructuredText syntax is
+also supported.
+
+```{eval-rst}
+:tag-warning:`REVIEW!`
+:tags-primary:`foo, bar`
+```
+
+```restructuredtext
+:tag-warning:`REVIEW!`
+:tags-primary:`foo, bar`
+```
+````
+
+
+---
+
+_This page is written in Markedly Structured Text (MyST Markdown)._
+
+
+[semantic colors]: https://sphinx-design.readthedocs.io/en/latest/css_classes.html#colors

sphinx_design_elements/compiled/style.css

@@ -19,3 +19,12 @@
 .sd-col > .highlight-restructuredtext {
   margin: unset;
 }
+
+
+/* Info card */
+
+/* Fix grid item formatting. */
+.sd-col > div.line-block {
+  margin-top: unset;
+  margin-bottom: unset;
+}

sphinx_design_elements/extension.py

@@ -9,6 +9,8 @@
 
 from . import compiled as static_module
 from .gridtable import setup_gridtable
+from .infocard import setup_infocard
+from .tag import setup_tags
 
 
 def setup_extension(app: Sphinx) -> None:
@@ -21,6 +23,8 @@ def setup_extension(app: Sphinx) -> None:
     app.add_node(nodes.container, override=True, html=(visit_container, depart_container))
 
     setup_gridtable(app)
+    setup_infocard(app)
+    setup_tags(app)
 
 
 def update_css_js(app: Sphinx):