✨ Add article-info directive

Author: chrisjsewell

MANIFEST.in

@@ -19,5 +19,5 @@ include README.md
 include sphinx_design/py.typed
 include sphinx_design/compiled/style.min.css
 include sphinx_design/compiled/sd_tabs.js
-include sphinx_design/compiled/opticon_LICENSE
-include sphinx_design/compiled/opticons.json
+include sphinx_design/compiled/octicon_LICENSE
+include sphinx_design/compiled/octicons.json

README.md

@@ -48,6 +48,8 @@ grids items cannot contain headers; is this in anyway possible with docutils str
 
 naming of directives/roles: standard prefix?
 
+why are cards setup with "word-wrap: break-word;"?
+
 check grid-items and tab-items are inside parents (or auto-wrap?)
 
 handle latex

docs/images/mugshot.jpeg

@@ -1,9 +1,19 @@
 # sphinx-design
 
+```{article-info}
+:avatar: images/mugshot.jpeg
+:avatar-link: https://github.com/chrisjsewell
+:author: "[Chris Sewell](https://github.com/chrisjsewell)"
+:date: "{sub-ref}`today`"
+:read-time: "{sub-ref}`wordcount-minutes` min read"
+```
+
 A sphinx extension for designing beautiful, size responsive web components.
 
 Created with inspiration from [Bootstrap](https://getbootstrap.com/) (v5), [Material Design](https://material.io) and [Material-UI](https://material-ui.com/) design frameworks.
 
+(cards)=
+
 ## Cards
 
 :::{card} Align Center
@@ -32,6 +42,8 @@ Content
 
 paragraph
 
+(grids)=
+
 ## Grids
 
 ::::{grid} 1 2 2 3
@@ -159,67 +171,7 @@ E
 
 ::::::
 
-(badges)=
-
-## Badges
-
-- {bdg}`plain badge`
-- {bdg-primary}`primary` {bdg-primary-line}`primary-line`
-- {bdg-secondary}`secondary` {bdg-secondary-line}`secondary-line`
-- {bdg-success}`success` {bdg-success-line}`success-line`
-- {bdg-info}`info` {bdg-info-line}`info-line`
-- {bdg-warning}`warning` {bdg-warning-line}`warning-line`
-- {bdg-danger}`danger` {bdg-danger-line}`danger-line`
-- {bdg-light}`light` {bdg-light-line}`light-line`
-- {bdg-dark}`dark` {bdg-dark-line}`dark-line`
-
-{bdg-link-primary}`name <https://example.com>`
-
-{bdg-link-primary-line}`name <https://example.com>`
-
-{bdg-ref-primary}`badges`
-
-(buttons)=
-
-### Buttons
-
-```{button-link} https://example.com
-```
-
-```{button-ref} buttons
-```
-
-```{button-link} https://example.com
-Button text
-```
-
-```{button-ref} buttons
-Button text
-```
-
-```{button-link} https://example.com
-:color: primary
-```
-
-```{button-link} https://example.com
-:color: primary
-:outline:
-```
-
-```{button-link} https://example.com
-:color: secondary
-:expand:
-```
-
-:::{card} Card with an expanded button
-:hover:
-
-```{button-link} https://example.com
-:color: info
-:click-parent:
-```
-
-:::
+(dropdown)=
 
 ## Dropdown
 
@@ -261,11 +213,7 @@ Dropdown content
 
 :::::
 
-## Icons
-
-Some {opticon-16}`report;sd-text-info` middle {opticon-24}`report` more text
-
-{fas}`spinner;sd-bg-primary sd-bg-text-primary fa-2x`
+(tabs)=
 
 ## Tabs
 
@@ -356,3 +304,73 @@ Content 2
 :::::
 
 ::::::
+
+(badges)=
+
+## Badges
+
+- {bdg}`plain badge`
+- {bdg-primary}`primary` {bdg-primary-line}`primary-line`
+- {bdg-secondary}`secondary` {bdg-secondary-line}`secondary-line`
+- {bdg-success}`success` {bdg-success-line}`success-line`
+- {bdg-info}`info` {bdg-info-line}`info-line`
+- {bdg-warning}`warning` {bdg-warning-line}`warning-line`
+- {bdg-danger}`danger` {bdg-danger-line}`danger-line`
+- {bdg-light}`light` {bdg-light-line}`light-line`
+- {bdg-dark}`dark` {bdg-dark-line}`dark-line`
+
+{bdg-link-primary}`name <https://example.com>`
+
+{bdg-link-primary-line}`name <https://example.com>`
+
+{bdg-ref-primary}`badges`
+
+(buttons)=
+
+## Buttons
+
+```{button-link} https://example.com
+```
+
+```{button-ref} buttons
+```
+
+```{button-link} https://example.com
+Button text
+```
+
+```{button-ref} buttons
+Button text
+```
+
+```{button-link} https://example.com
+:color: primary
+```
+
+```{button-link} https://example.com
+:color: primary
+:outline:
+```
+
+```{button-link} https://example.com
+:color: secondary
+:expand:
+```
+
+:::{card} Card with an expanded button
+:hover:
+
+```{button-link} https://example.com
+:color: info
+:click-parent:
+```
+
+:::
+
+(icons)=
+
+## Icons
+
+Some {octicon-16}`report;sd-text-info` middle {octicon-24}`report` more text
+
+{fas}`spinner;sd-bg-primary sd-bg-text-primary fa-2x`

docs/index.md

@@ -0,0 +1,178 @@
+from typing import List, Optional
+
+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 create_component
+
+
+def setup_article_info(app: Sphinx):
+    """Setup the article information components."""
+    app.add_directive("article-info", ArticleInfoDirective)
+
+
+class ArticleInfoDirective(SphinxDirective):
+    """ """
+
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+    option_spec = {
+        "avatar": directives.uri,
+        "avatar-alt": directives.unchanged,
+        "avatar-link": directives.uri,
+        "author": directives.unchanged_required,
+        "date": directives.unchanged_required,
+        "read-time": directives.unchanged_required,
+        "class": directives.class_option,
+    }
+
+    def _parse_text(
+        self, text: str, icon: Optional[nodes.Node] = None, parse: bool = False
+    ) -> nodes.Node:
+        """Parse the text."""
+        if not parse:
+            output = ([icon] if icon else []) + [nodes.Text(text)]
+        else:
+            text_nodes, _ = self.state.inline_text(text, self.lineno)
+            text_nodes = ([icon] if icon else []) + text_nodes
+            para = nodes.paragraph("", "", *text_nodes, classes=["sd-p-0", "sd-m-0"])
+            self.set_source_info(para)
+            output = [para]
+        return output
+
+    def run(self) -> List[nodes.Node]:
+        """Run the directive."""
+        parse_fields = True  # parse field text
+
+        top_grid = create_component(
+            "grid-container",
+            [
+                "sd-container-fluid",
+                "sd-sphinx-override",
+                "sd-p-0",
+                "sd-mt-2",
+                "sd-mb-4",
+            ]
+            + self.options.get("class", []),
+        )
+        self.set_source_info(top_grid)
+
+        top_row = create_component(
+            "grid-row",
+            [
+                "sd-row",
+                "sd-row-cols-2",
+                "sd-g-1",
+            ],
+        )
+        self.set_source_info(top_row)
+        top_grid += top_row
+
+        avatar_uri = self.options.get("avatar")
+        if avatar_uri:
+            avatar_column = create_component(
+                "grid-item",
+                ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
+            )
+            self.set_source_info(avatar_column)
+            avatar_image = nodes.image(
+                "",
+                uri=avatar_uri,
+                alt=self.options.get("avatar-alt", ""),
+                classes=["sd-avatar-sm"],
+            )
+            self.set_source_info(avatar_image)
+            if self.options.get("avatar-link"):
+                avatar_link = nodes.reference(
+                    "", "", refuri=self.options.get("avatar-link")
+                )
+                avatar_link += avatar_image
+                avatar_image = avatar_link
+            avatar_column += avatar_image
+            top_row += avatar_column
+
+        info_column = create_component(
+            "grid-item",
+            ["sd-col", "sd-d-flex", "sd-align-items-center"],
+        )
+        self.set_source_info(info_column)
+        top_row += info_column
+
+        info_grid = create_component(
+            "grid-container",
+            [
+                "sd-container-fluid",
+                "sd-sphinx-override",
+            ],
+        )
+        self.set_source_info(info_grid)
+        info_column += info_grid
+
+        info_row = create_component(
+            "grid-row",
+            [
+                "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",
+            ],
+        )
+        self.set_source_info(info_row)
+        info_grid += info_row
+
+        author_text = self.options.get("author")
+        if author_text:
+            author_column = create_component(
+                "grid-item",
+                ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
+            )
+            self.set_source_info(author_column)
+            author_nodes = self._parse_text(author_text, parse=parse_fields)
+            author_column.extend(author_nodes)
+            info_row += author_column
+
+        date_text = self.options.get("date")
+        if date_text:
+            date_column = create_component(
+                "grid-item",
+                ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
+            )
+            self.set_source_info(date_column)
+            date_icon = nodes.raw(
+                "",
+                nodes.Text(get_octicon("calendar", size=16)),
+                classes=["sd-pr-2"],
+                format="html",
+            )
+            date_nodes = self._parse_text(date_text, icon=date_icon, parse=parse_fields)
+            date_column.extend(date_nodes)
+            info_row += date_column
+
+        read_time_text = self.options.get("read-time")
+        if read_time_text:
+            read_time_column = create_component(
+                "grid-item",
+                ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
+            )
+            self.set_source_info(read_time_column)
+            read_time_icon = nodes.raw(
+                "",
+                nodes.Text(get_octicon("clock", size=16)),
+                classes=["sd-pr-2"],
+                format="html",
+            )
+            read_time_nodes = self._parse_text(
+                read_time_text, icon=read_time_icon, parse=parse_fields
+            )
+            read_time_column.extend(read_time_nodes)
+            info_row += read_time_column
+
+        return [top_grid]