✨ NEW: Create custom directives (#194)

You can use the `sd_custom_directives` configuration option in your `conf.py` to add custom directives, with default option values:

```python
sd_custom_directives = {
    "dropdown-syntax": {
        "inherit": "dropdown",
        "argument": "Syntax",
        "options": {
            "color": "primary",
            "icon": "code",
        },
    }
}
```

The key is the new directive name to add, and the value is a dictionary with the following keys:

- `inherit`: The directive to inherit from (e.g. `dropdown`)
- `argument`: The default argument (optional, only for directives that take a single argument)
- `options`: A dictionary of default options for the directive (optional)

Author: chrisjsewell

docs/additional.md

@@ -19,9 +19,7 @@ normally positioned just below the title of the article (shown below with non-st
 :class-container: sd-p-2 sd-outline-muted sd-rounded-1
 ```
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/article-info.txt

docs/badges_buttons.md

@@ -17,9 +17,7 @@ Badges are available in each semantic color, with filled and outline variants:
 - {bdg-light}`light`, {bdg-light-line}`light-line`
 - {bdg-dark}`dark`, {bdg-dark-line}`dark-line`
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/badge-basic.txt
@@ -40,9 +38,7 @@ The syntax is the same as for the `ref` role.
 
 {bdg-ref-primary}`badges`
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/badge-link.txt
@@ -94,9 +90,7 @@ Button text
 Reference Button text
 ```
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/button-link.txt

docs/cards.md

@@ -13,9 +13,7 @@ Card content
 
 See the [Material Design](https://material.io/components/cards) and [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) descriptions for further details.
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/card-basic.txt
@@ -38,9 +36,7 @@ Card content
 Footer
 :::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/card-head-foot.txt
@@ -115,9 +111,7 @@ Footer
 
 :::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/card-images.txt
@@ -151,9 +145,7 @@ The entire card can be clicked to navigate to <https://example.com>.
 The entire card can be clicked to navigate to the `cards-clickable` reference target.
 :::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/card-link.txt
@@ -223,9 +215,7 @@ content
 :::
 ::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/card-carousel.txt

docs/conf.py

@@ -10,6 +10,16 @@
 
 suppress_warnings = ["design.fa-build"]
 sd_fontawesome_latex = True
+sd_custom_directives = {
+    "dropdown-syntax": {
+        "inherit": "dropdown",
+        "argument": "Syntax",
+        "options": {
+            "color": "primary",
+            "icon": "code",
+        },
+    }
+}
 
 html_theme = os.environ.get("SPHINX_THEME", "alabaster")
 html_title = f"Sphinx Design ({html_theme.replace('_', '-')})"

docs/css_classes.md

@@ -9,9 +9,7 @@ All CSS classes that are part of sphinx-design are prefixed with `sd-`.
 Some CSS styled text
 :::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/div-basic.txt

docs/dropdowns.md

@@ -20,9 +20,7 @@ Dropdown content
 Dropdown content
 :::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/dropdown-basic.txt

docs/get_started.md

@@ -43,6 +43,29 @@ sd_hide_title: true
 :::
 ::::
 
+### Creating custom directives
+
+You can use the `sd_custom_directives` configuration option in your `conf.py` to add custom directives, with default option values:
+
+```python
+sd_custom_directives = {
+    "dropdown-syntax": {
+        "inherit": "dropdown",
+        "argument": "Syntax",
+        "options": {
+            "color": "primary",
+            "icon": "code",
+        },
+    }
+}
+```
+
+The key is the new directive name to add, and the value is a dictionary with the following keys:
+
+- `inherit`: The directive to inherit from (e.g. `dropdown`)
+- `argument`: The default argument (optional, only for directives that take a single argument)
+- `options`: A dictionary of default options for the directive (optional)
+
 ## Supported browsers
 
 - Chrome >= 60

docs/grids.md

@@ -29,9 +29,7 @@ D
 :::
 ::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/grid-basic.txt
@@ -80,9 +78,7 @@ B
 :::
 ::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/grid-card.txt
@@ -121,9 +117,7 @@ B
 :::
 ::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/grid-gutter.txt
@@ -160,9 +154,7 @@ C
 :::
 ::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/grid-card-columns.txt
@@ -254,9 +246,7 @@ Content
 
 ::::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/grid-nested.txt

docs/tabs.md

@@ -17,9 +17,7 @@ Content 2
 
 ::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/tab-basic.txt
@@ -70,9 +68,7 @@ Content 2
 
 ::::
 
-`````{dropdown} Syntax
-:icon: code
-:color: primary
+`````{dropdown-syntax}
 
 ````{tab-set-code}
 ```{literalinclude} ./snippets/myst/tab-sync.txt

sphinx_design/article_info.py

@@ -3,18 +3,17 @@
 from docutils import nodes
 from docutils.parsers.rst import directives
 from sphinx.application import Sphinx
-from sphinx.util.docutils import SphinxDirective
 
 from .icons import get_octicon
-from .shared import SEMANTIC_COLORS, create_component, make_choice
+from .shared import SEMANTIC_COLORS, SdDirective, create_component, make_choice
 
 
 def setup_article_info(app: Sphinx):
     """Setup the article information components."""
     app.add_directive("article-info", ArticleInfoDirective)
 
 
-class ArticleInfoDirective(SphinxDirective):
+class ArticleInfoDirective(SdDirective):
     """ """
 
     has_content = False
@@ -48,8 +47,7 @@ def _parse_text(
             output = [para]
         return output
 
-    def run(self) -> list[nodes.Node]:  # noqa: PLR0915
-        """Run the directive."""
+    def run_with_defaults(self) -> list[nodes.Node]:  # noqa: PLR0915
         parse_fields = True  # parse field text
 
         top_grid = create_component(