📚 DOCS: Add article-info documentation

Author: chrisjsewell

docs/additional.md

@@ -0,0 +1,72 @@
+(special)=
+
+# Additional
+
+These are additional components that are not part of the standard Materials Design or Bootstrap systems.
+
+## `article-info`
+
+This directive is used to display a block of information about an article,
+normally positioned just below the title of the article (show below with non-standard outline).
+
+```{article-info}
+:avatar: images/ebp-logo.png
+:avatar-link: https://executablebooks.org/
+:avatar-outline: muted
+:author: Executable Books
+:date: "Jul 24, 2021"
+:read-time: "5 min read"
+:class-container: sd-p-2 sd-outline-muted sd-rounded-1
+```
+
+`````{dropdown} Syntax
+:icon: code
+:color: light
+
+````{tab-set-code}
+```{literalinclude} ./snippets/myst/article-info.txt
+:language: markdown
+```
+```{literalinclude} ./snippets/rst/article-info.txt
+:language: rst
+```
+````
+`````
+
+The `author`, `date`, and `read-time` options are parsed as syntax,
+so you can use substitutions like:
+
+- `date`
+  - MyST: `` :date: "{sub-ref}`today`" ``
+  - RST: `:data: |today|`
+- `read-time`
+  - MyST: `` :read-time: "{sub-ref}`wordcount-minutes` min read" ``
+
+### options
+
+avatar
+: A URI (relative file path or URL) to an image for use as the avatar.
+
+avatar-alt
+: Alternative text for the avatar.
+
+avatar-link
+: A URL to link to if the avatar icon is clicked.
+
+avatar-outline
+: A semantic color to use for the outline of the avatar.
+
+author
+: Text to display in the author of of the article.
+
+date
+: Text to display in the date of the article.
+
+read-time
+: Text to indicate the time to read the article.
+
+class-container
+: Additional CSS classes for the container element.
+
+class-avatar
+: Additional CSS classes for the avatar element.

docs/conf.py

@@ -8,7 +8,7 @@
 extensions = ["myst_parser", "sphinx_design"]
 
 html_theme = os.environ.get("SPHINX_THEME", "alabaster")
-html_title = f"Sphinx Design ({html_theme.replace('_', '-')}"
+html_title = f"Sphinx Design ({html_theme.replace('_', '-')})"
 
 if html_theme == "alabaster":
     html_css_files = [

docs/images/ebp-logo.png

@@ -31,6 +31,7 @@ cards
 dropdowns
 tabs
 badges_buttons
+additional
 ```
 
 ```{toctree}

docs/index.md

@@ -0,0 +1,9 @@
+```{article-info}
+:avatar: ebp-logo.png
+:avatar-link: https://executablebooks.org/
+:avatar-outline: muted
+:author: Executable Books
+:date: Jul 24, 2021
+:read-time: 5 min read
+:class-container: sd-p-2 sd-outline-muted sd-rounded-1
+```

docs/snippets/myst/_article-info.txt

@@ -0,0 +1,8 @@
+.. article-info::
+    :avatar: ebp-logo.png
+    :avatar-link: https://executablebooks.org/
+    :avatar-outline: muted
+    :author: Executable Books
+    :date: Jul 24, 2021
+    :read-time: 5 min read
+    :class-container: sd-p-2 sd-outline-muted sd-rounded-1

docs/snippets/myst/article-info.txt

@@ -6,7 +6,7 @@
 from sphinx.util.docutils import SphinxDirective
 
 from .icons import get_octicon
-from .shared import create_component
+from .shared import SEMANTIC_COLORS, create_component, make_choice
 
 
 def setup_article_info(app: Sphinx):
@@ -24,10 +24,12 @@ class ArticleInfoDirective(SphinxDirective):
         "avatar": directives.uri,
         "avatar-alt": directives.unchanged,
         "avatar-link": directives.uri,
+        "avatar-outline": make_choice(SEMANTIC_COLORS),
         "author": directives.unchanged_required,
         "date": directives.unchanged_required,
         "read-time": directives.unchanged_required,
-        "class": directives.class_option,
+        "class-container": directives.class_option,
+        "class-avatar": directives.class_option,
     }
 
     def _parse_text(
@@ -59,17 +61,13 @@ def run(self) -> List[nodes.Node]:
                 "sd-mt-2",
                 "sd-mb-4",
             ]
-            + self.options.get("class", []),
+            + self.options.get("class-container", []),
         )
         self.set_source_info(top_grid)
 
         top_row = create_component(
             "grid-row",
-            [
-                "sd-row",
-                "sd-row-cols-2",
-                "sd-g-1",
-            ],
+            ["sd-row", "sd-row-cols-2", "sd-gx-2", "sd-gy-1"],
         )
         self.set_source_info(top_row)
         top_grid += top_row
@@ -82,11 +80,16 @@ def run(self) -> List[nodes.Node]:
                 ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
             )
             self.set_source_info(avatar_column)
+            avatar_classes = ["sd-avatar-sm"]
+            if "avatar-outline" in self.options:
+                avatar_classes.append(f"sd-outline-{self.options['avatar-outline']}")
+            if "class-avatar" in self.options:
+                avatar_classes += self.options["class-avatar"]
             avatar_image = nodes.image(
                 "",
                 uri=avatar_uri,
                 alt=self.options.get("avatar-alt", ""),
-                classes=["sd-avatar-sm"],
+                classes=avatar_classes,
             )
             self.set_source_info(avatar_image)
             if self.options.get("avatar-link"):

docs/snippets/rst/article-info.txt

@@ -14,6 +14,7 @@
 def write_assets(src_path: Path):
     """Write additional assets to the src directory."""
     src_path.joinpath("snippet.py").write_text("a = 1")
+    src_path.joinpath("ebp-logo.png").touch()
 
 
 @pytest.mark.parametrize(

sphinx_design/article_info.py

@@ -0,0 +1,25 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-container-fluid sd-sphinx-override sd-p-0 sd-mt-2 sd-mb-4 sd-p-2 sd-outline-muted sd-rounded-1" design_component="grid-container" is_div="True">
+            <container classes="sd-row sd-row-cols-2 sd-gx-2 sd-gy-1" design_component="grid-row" is_div="True">
+                <container classes="sd-col sd-col-auto sd-d-flex sd-align-items-center" design_component="grid-item" is_div="True">
+                    <reference refuri="https://executablebooks.org/">
+                        <image alt="" candidates="{'*': 'ebp-logo.png'}" classes="sd-avatar-sm sd-outline-muted" uri="ebp-logo.png">
+                <container classes="sd-col sd-d-flex sd-align-items-center" design_component="grid-item" is_div="True">
+                    <container classes="sd-container-fluid sd-sphinx-override" design_component="grid-container" is_div="True">
+                        <container classes="sd-row sd-row-cols-2 sd-row-cols-xs-2 sd-row-cols-sm-3 sd-row-cols-md-3 sd-row-cols-lg-3 sd-gx-3 sd-gy-1" design_component="grid-row" is_div="True">
+                            <container classes="sd-col sd-col-auto sd-d-flex sd-align-items-center" design_component="grid-item" is_div="True">
+                                <paragraph classes="sd-p-0 sd-m-0">
+                                    Executable Books
+                            <container classes="sd-col sd-col-auto sd-d-flex sd-align-items-center" design_component="grid-item" is_div="True">
+                                <paragraph classes="sd-p-0 sd-m-0">
+                                    <raw classes="sd-pr-2" format="html" xml:space="preserve">
+                                        <svg version="1.1" width="16" height="16" class="sd-octicon sd-octicon-calendar" viewBox="0 0 16 16" aria-hidden="true"><path fill-rule="evenodd" d="M4.75 0a.75.75 0 01.75.75V2h5V.75a.75.75 0 011.5 0V2h1.25c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0113.25 16H2.75A1.75 1.75 0 011 14.25V3.75C1 2.784 1.784 2 2.75 2H4V.75A.75.75 0 014.75 0zm0 3.5h8.5a.25.25 0 01.25.25V6h-11V3.75a.25.25 0 01.25-.25h2zm-2.25 4v6.75c0 .138.112.25.25.25h10.5a.25.25 0 00.25-.25V7.5h-11z"></path></svg>
+                                    Jul 24, 2021
+                            <container classes="sd-col sd-col-auto sd-d-flex sd-align-items-center" design_component="grid-item" is_div="True">
+                                <paragraph classes="sd-p-0 sd-m-0">
+                                    <raw classes="sd-pr-2" format="html" xml:space="preserve">
+                                        <svg version="1.1" width="16" height="16" class="sd-octicon sd-octicon-clock" viewBox="0 0 16 16" aria-hidden="true"><path fill-rule="evenodd" d="M1.5 8a6.5 6.5 0 1113 0 6.5 6.5 0 01-13 0zM8 0a8 8 0 100 16A8 8 0 008 0zm.5 4.75a.75.75 0 00-1.5 0v3.5a.75.75 0 00.471.696l2.5 1a.75.75 0 00.557-1.392L8.5 7.742V4.75z"></path></svg>
+                                    5 min read