✨ NEW: Add ref-type option to button-ref directive (#19)

Author: chrisjsewell

README.md

@@ -74,8 +74,6 @@ subtitle for card (see <https://material.io/components/cards#anatomy>)
 
 rtd PRs not working
 
-octicon in button text shown as raw HTML
-
 
 [github-ci]: https://github.com/executablebooks/sphinx-design/workflows/continuous-integration/badge.svg?branch=main
 [github-link]: https://github.com/executablebooks/sphinx-design

docs/badges_buttons.md

@@ -108,6 +108,25 @@ Reference Button text
 ````
 `````
 
+Note that by default sphinx converts the content of references to raw text.
+For example `**Bold text**` with `ref-type` set to `ref` will be rendered without bold:
+
+```{button-ref} buttons
+:ref-type: ref
+:color: primary
+
+**Bold text**
+```
+
+However, if using [myst-parser](https://myst-parser.readthedocs.io/), you can set the `ref-type` to `myst`, and the content will be properly rendered:
+
+```{button-ref} buttons
+:ref-type: myst
+:color: primary
+
+**Bold text**
+```
+
 Use the `click-parent` option to make the button's parent container also clickable.
 
 :::{card} Card with an expanded button
@@ -124,6 +143,9 @@ See the [Material Design](https://material.io/components/buttons) and [Bootstrap
 
 ### `button-link` and `button-ref` options
 
+ref-type (`button-ref` only)
+: Type of reference to use; `any` (default), `ref`, `doc`, or `myst`
+
 color
 : Set the color of the button (background and font).
   One of the semantic color names: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`, `muted`.
@@ -132,7 +154,7 @@ outline
 : Outline color variant
 
 align
-: Align the button on the page; left, right, center or justify
+: Align the button on the page; `left`, `right`, `center` or `justify`
 
 expand
 : Expand to fit parent width

docs/index.md

@@ -29,9 +29,10 @@ sd_hide_title: true
 A sphinx extension for designing beautiful, screen-size responsive web-components.
 
 ```{button-ref} get_started
+:ref-type: doc
 :outline:
 :color: white
-:class: sd-fs-5
+:class: sd-px-4 sd-fs-5
 
 Get Started
 ```

sphinx_design/badges_buttons.py

@@ -144,6 +144,8 @@ class _ButtonDirective(SphinxDirective):
         "click-parent": directives.flag,
         "tooltip": directives.unchanged_required,
         "shadow": directives.flag,
+        # ref button only
+        "ref-type": make_choice(["any", "ref", "doc", "myst"]),
         "class": directives.class_option,
     }
 
@@ -174,13 +176,16 @@ def run(self) -> List[nodes.Node]:
         self.set_source_info(node)
         if "tooltip" in self.options:
             node["reftitle"] = self.options["tooltip"]  # TODO escape HTML
+
         if self.content:
             textnodes, _ = self.state.inline_text(
                 "\n".join(self.content), self.lineno + self.content_offset
             )
-            node.extend(textnodes)
+            content = nodes.inline("", "")
+            content.extend(textnodes)
         else:
-            node += nodes.inline(target, target)
+            content = nodes.inline(target, target)
+        node.append(content)
 
         if "expand" in self.options:
             grid_container = nodes.inline(classes=["sd-d-grid"])
@@ -217,13 +222,14 @@ def create_ref_node(
         self, rawtext: str, target: str, explicit_title: bool, classes: List[str]
     ) -> nodes.Node:
         """Create the reference node."""
+        ref_type = self.options.get("ref-type", "any")
         options = {
             # TODO the presence of classes raises an error if the link cannot be found
             "classes": classes,
             "reftarget": target,
             "refdoc": self.env.docname,
-            "refdomain": "",
-            "reftype": "any",  # TODO allow for variable ref type
+            "refdomain": "std" if ref_type in {"ref", "doc"} else "",
+            "reftype": ref_type,
             "refexplicit": explicit_title,
             "refwarn": True,
         }

tests/test_snippets/snippet_post_button-link.xml

@@ -8,7 +8,8 @@
                     https://example.com
         <paragraph>
             <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
-                Button text
+                <inline>
+                    Button text
         <paragraph>
             <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
                 <inline>

tests/test_snippets/snippet_pre_button-link.xml

@@ -8,7 +8,8 @@
                     https://example.com
         <paragraph>
             <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
-                Button text
+                <inline>
+                    Button text
         <paragraph>
             <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
                 <inline>