✨ Add multi-theme doc generation

Author: chrisjsewell

README.md

@@ -1,6 +1,6 @@
 # sphinx-design (IN-DEVELOPMENT)
 
-A sphinx extension for designing beautiful, size responsive web components.
+A sphinx extension for designing beautiful, view 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.
 
@@ -53,5 +53,8 @@ card header/footer syntax?
 
 Use autoprefixer when compiling SASS (see <https://getbootstrap.com/docs/5.0/getting-started/browsers-devices/#supported-browsers>)
 
-horizontal card (grid row inside card),
+horizontal card (grid row inside card, picture on left)
+
 avatars (rounded images)
+
+horizontally scrollable cards: (see <https://stackoverflow.com/questions/35993300/horizontally-scrollable-list-of-cards-in-bootstrap>)

docs/conf.py

@@ -1,11 +1,15 @@
 """Configuration file for the Sphinx documentation builder."""
+import os
 
 project = "Sphinx Design"
 copyright = "2021, Executable Book Project"
 author = "Executable Book Project"
 
 extensions = ["myst_parser", "sphinx_design"]
 
+html_theme = os.environ.get("SPHINX_THEME", "alabaster")
+html_title = f"Sphinx Design ({html_theme})"
+
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 myst_enable_extensions = ["colon_fence", "substitution"]
 

docs/index.md

@@ -4,6 +4,34 @@ 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
+
+:::{card}
+:width: 25
+:margin: 0 2 auto auto
+:text-align: center
+
+align center
+:::
+
+:::{card}
+:width: 50
+:margin: 0 2 auto 0
+:text-align: right
+
+align right
+:::
+
+:::{card}
+:width: 50
+:margin: 0 2 0 auto
+:text-align: left
+
+align left
+:::
+
+paragraph
+
 ## Grids
 
 ::::{grid}
@@ -78,22 +106,6 @@ next paragraph 1
 
 ::::
 
-## Cards
-
-:::{card}
-:width: 25
-:align: center
-
-align center
-:::
-
-:::{card}
-:width: 50
-:align: right
-
-align right
-:::
-
 (badges)=
 
 ## Badges
@@ -147,6 +159,7 @@ Button text
 ```
 
 :::{card} Card with an expanded button
+:hover:
 
 ```{button-link} https://example.com
 :color: info

setup.cfg

@@ -1,7 +1,7 @@
 [metadata]
 name = sphinx_design
 version = attr: sphinx_design.__version__
-description = A sphinx extension for designing beautiful, size responsive web components.
+description = A sphinx extension for designing beautiful, view size responsive web components.
 long_description = file: README.md
 long_description_content_type = text/markdown
 url = https://github.com/executablebooks/sphinx-design
@@ -41,6 +41,14 @@ testing =
     pytest~=5.4
     pytest-cov
     pytest-regressions
+theme_furo =
+    furo==2021.7.5b38
+theme_pydata =
+    pydata-sphinx-theme~=0.6.0
+theme_rtd =
+    sphinx-rtd-theme~=0.5.0
+theme_sbt =
+    sphinx-book-theme~=0.1.0
 
 [options.packages.find]
 exclude =

sphinx_design/__init__.py

@@ -1,4 +1,4 @@
-"""A sphinx extension for designing beautiful, size responsive web components."""
+"""A sphinx extension for designing beautiful, view size responsive web components."""
 from typing import TYPE_CHECKING
 
 __version__ = "0.0.1"

sphinx_design/badges_buttons.py

@@ -147,7 +147,7 @@ class _ButtonDirective(SphinxDirective):
 
     def create_ref_node(
         self, rawtext: str, target: str, explicit_title: bool, classes: List[str]
-    ):
+    ) -> nodes.Node:
         """Create the reference node."""
         raise NotImplementedError
 
@@ -197,7 +197,7 @@ class ButtonLinkDirective(_ButtonDirective):
 
     def create_ref_node(
         self, rawtext: str, target: str, explicit_title: bool, classes: List[str]
-    ):
+    ) -> nodes.Node:
         """Create the reference node."""
         return nodes.reference(
             rawtext,
@@ -211,14 +211,14 @@ class ButtonRefDirective(_ButtonDirective):
 
     def create_ref_node(
         self, rawtext: str, target: str, explicit_title: bool, classes: List[str]
-    ):
+    ) -> nodes.Node:
         """Create the reference node."""
         options = {
             "classes": classes,
             "reftarget": target,
             "refdoc": self.env.docname,
             "refdomain": "",
-            "reftype": "any",
+            "reftype": "any",  # TODO allow for variable ref type
             "refexplicit": explicit_title,
             "refwarn": True,
         }

sphinx_design/cards.py

@@ -7,7 +7,7 @@
 from sphinx.application import Sphinx
 from sphinx.util.docutils import SphinxDirective
 
-from .shared import create_component, make_choice, text_align
+from .shared import create_component, make_choice, margin_option, text_align
 
 DIRECTIVE_NAME_CARD = "card"
 REGEX_HEADER = re.compile(r"^\^{3,}\s*$")
@@ -40,11 +40,12 @@ class CardDirective(SphinxDirective):
     option_spec = {
         # TODO adaptive width/ width based on content
         "width": make_choice(["auto", "25", "50", "75", "100"]),
-        "align": make_choice(["left", "center", "right"]),
+        "margin": margin_option,
         "text-align": text_align,
         "img-top": directives.uri,
         "img-bottom": directives.uri,
         "no-shadow": directives.flag,
+        "hover": directives.flag,
         "class-card": directives.class_option,
         "class-header": directives.class_option,
         "class-body": directives.class_option,
@@ -64,15 +65,12 @@ def create_card(
         card_classes = ["sd-card", "sd-sphinx-override"]
         if "width" in options:
             card_classes += [f'sd-w-{options["width"]}']
-        if "align" in options:
-            align_class = {
-                "center": "sd-mx-auto",
-                "left": "sd-mr-auto",
-                "right": "sd-ml-auto",
-            }[options["align"]]
-            card_classes += [align_class]
+        if "margin" in options:
+            card_classes += options["margin"]
         if "no-shadow" not in options:
             card_classes += ["sd-shadow"]
+        if "hover" in options:
+            card_classes += ["sd-card-hover"]
         card = create_component(
             "card",
             card_classes

sphinx_design/compiled/style.min.css

@@ -198,6 +198,7 @@ class GridItemCardDirective(SphinxDirective):
         "img-top": directives.uri,
         "img-bottom": directives.uri,
         "no-shadow": directives.flag,
+        "hover": directives.flag,
         "class-item": directives.class_option,
         "class-card": directives.class_option,
         "class-body": directives.class_option,
@@ -229,6 +230,7 @@ def run(self) -> List[nodes.Node]:
                 "img-top",
                 "img-bottom",
                 "no-shadow",
+                "hover",
                 "class-card",
                 "class-body",
                 "class-title",

sphinx_design/grids.py

@@ -35,26 +35,26 @@ def make_choice(choices: Sequence[str]):
     return lambda argument: directives.choice(argument, choices)
 
 
-def _margin_or_padding_option(argument: Optional[str], class_prefix: str) -> List[str]:
+def _margin_or_padding_option(
+    argument: Optional[str],
+    class_prefix: str,
+    allowed: Sequence[str],
+) -> List[str]:
     """Validate the margin/padding is one (all) or four (top bottom left right) integers,
-    between 0 and 5.
+    between 0 and 5 or 'auto'.
     """
     if argument is None:
         raise ValueError("argument required but none supplied")
     values = argument.split()
-    try:
-        int_values = [int(value) for value in values]
-    except Exception:
-        raise ValueError("argument must be space separated list of integers")
-    for value in int_values:
-        if not 0 <= value <= 5:
-            raise ValueError("argument must be integers in range 0 to 5")
+    for value in values:
+        if value not in allowed:
+            raise ValueError(f"{value} is not in: {allowed}")
     if len(values) == 1:
         return [f"{class_prefix}-{values[0]}"]
     if len(values) == 4:
         return [
             f"{class_prefix}{side}-{value}"
-            for side, value in zip(["t", "b", "l", "r"], int_values)
+            for side, value in zip(["t", "b", "l", "r"], values)
         ]
     raise ValueError(
         "argument must be one (all) or four (top bottom left right) integers"
@@ -63,16 +63,18 @@ def _margin_or_padding_option(argument: Optional[str], class_prefix: str) -> Lis
 
 def margin_option(argument: Optional[str]) -> List[str]:
     """Validate the margin is one (all) or four (top bottom left right) integers,
-    between 0 and 5.
+    between 0 and 5 or 'auto'.
     """
-    return _margin_or_padding_option(argument, "sd-m")
+    return _margin_or_padding_option(
+        argument, "sd-m", ("auto", "0", "1", "2", "3", "4", "5")
+    )
 
 
 def padding_option(argument: Optional[str]) -> List[str]:
     """Validate the padding is one (all) or four (top bottom left right) integers,
     between 0 and 5.
     """
-    return _margin_or_padding_option(argument, "sd-p")
+    return _margin_or_padding_option(argument, "sd-p", ("0", "1", "2", "3", "4", "5"))
 
 
 def text_align(argument: Optional[str]) -> List[str]:

sphinx_design/shared.py

@@ -59,19 +59,22 @@
     color: var(--sd-color-#{$color}-text) !important;
     background-color: var(--sd-color-#{$color}) !important;
     border-color: var(--sd-color-#{$color}) !important;
-    border: 1px solid !important;
+    border-width: 1px !important;
+    border-style: solid !important;
   }
   .sd-btn-#{$color}:hover,
   .sd-btn-#{$color}:focus {
     color: var(--sd-color-#{$color}-text) !important;
     background-color: var(--sd-color-#{$color}-highlight) !important;
     border-color: var(--sd-color-#{$color}-highlight) !important;
-    border: 1px solid !important;
+    border-width: 1px !important;
+    border-style: solid !important;
   }
   .sd-btn-outline-#{$color} {
     color: var(--sd-color-#{$color}) !important;
     border-color: var(--sd-color-#{$color}) !important;
-    border: 1px solid !important;
+    border-width: 1px !important;
+    border-style: solid !important;
   }
 }
 
@@ -85,5 +88,3 @@
   z-index: 1;
   content: "";
 }
-
-//

style/_button.scss

@@ -8,6 +8,7 @@
   background-color: var(--sd-color-card-background);
   border: 1px solid var(--sd-color-card-border);
   border-radius: 0.25rem;
+  color: var(--sd-color-card-text);
   display: -ms-flexbox;
   display: flex;
   -ms-flex-direction: column;
@@ -22,6 +23,10 @@
   }
 }
 
+.sd-card-hover:hover {
+  border-color: var(--sd-color-card-border-hover);
+}
+
 .sd-card-body {
   -ms-flex: 1 1 auto;
   flex: 1 1 auto;

style/_cards.scss

@@ -14,6 +14,7 @@ $black-0: rgba(0, 0, 0, 0) !default;
 $black-3: rgba(0, 0, 0, .03) !default;
 $black-12-5: rgba(0, 0, 0, .125) !default;
 $black-15: rgba(0, 0, 0, .15) !default;
+$black-25: rgba(0, 0, 0, .25) !default;
 $black-50: rgba(0, 0, 0, .5) !default;
 
 $blue: #007bff !default;
@@ -61,9 +62,11 @@ $semantic-colors: (
   --sd-color-shadow: #{$black-15};
   // cards
   --sd-color-card-border: #{$black-12-5};
-  --sd-color-card-background: #{$white};
-  --sd-color-card-header: #{$black-3};
-  --sd-color-card-footer: #{$black-3};
+  --sd-color-card-border-hover: #{$black-25};
+  --sd-color-card-background: transparent;
+  --sd-color-card-text: inherit;
+  --sd-color-card-header: transparent;
+  --sd-color-card-footer: transparent;
 }
 
 .sd-bg-transparent {