📚 Improve documentation

Author: chrisjsewell

README.md

@@ -4,9 +4,6 @@ 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.
 
-All components are principally based on CSS (not JavaScript),
-meaning they will be responsively rendered on any device.
-
 ## Supported browsers
 
 - Chrome >= 60
@@ -60,8 +57,6 @@ Use autoprefixer when compiling SASS (see <https://getbootstrap.com/docs/5.0/get
 
 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>)
 
 from inline-tabs:

docs/cards.md

@@ -0,0 +1,118 @@
+(cards)=
+
+# Cards
+
+A card is a flexible and extensible content container.
+It can be formatted with components including headers and footers, titles and images.
+
+:::{card} Card Title
+
+Card content
+:::
+
+All content before the first occurrence three or more `^^^` is considered as a header,
+and all content after the final occurrence of three or more `+++` is considered as a footer:
+
+:::{card} Card Title
+Header
+^^^
+Card content
++++
+Footer
+:::
+
+:::{card} Clickable Card (external)
+:link: https://example.com
+
+The entire card can be clicked to navigate to <https://example.com>.
+:::
+
+:::{card} Clickable Card (internal)
+:link: cards
+:link-type: ref
+
+The entire card can be clicked to navigate to the `cards` reference target.
+:::
+
+
+::::{grid} 1 2 2 2
+:::{grid-item-card} Card Title
+:img-top: images/banner.png
+:img-bottom: images/banner.png
+
+Header
+^^^
+Card content
++++
+Footer
+:::
+::::
+
+
+:::{card} Align Center
+:width: 75%
+:margin: 0 2 auto auto
+:text-align: center
+
+Content
+:::
+
+:::{card} Align Right
+:width: 50%
+:margin: 0 2 auto 0
+:text-align: right
+
+Content
+:::
+
+:::{card} Align Left
+:width: 50%
+:margin: 0 2 0 auto
+:text-align: left
+
+Content
+:::
+
+See the [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) for further details.
+
+## `card` options
+
+width
+: The width that the card should take up (in %): auto, 25%, 50%, 75%, 100%.
+
+margin
+: Outer margin of grid.
+  One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5, auto.
+
+text-align
+: Default horizontal text alignment: left, right, center or justify
+
+img-top
+: A URI (relative file path or URL) to an image to be placed above the content.
+
+img-bottom
+: A URI (relative file path or URL) to an image to be placed below the content.
+
+link
+: Turn the entire card into a clickable link to an external/internal target.
+
+link-type
+: Type of link: `url` (default), `ref`, `doc`, `any`.
+
+no-shadow
+: Do not draw a shadow around the card.
+
+class-card
+: Additional CSS classes for the card container element.
+
+class-header
+: Additional CSS classes for the header element.
+
+class-body
+: Additional CSS classes for the body element.
+
+class-title
+: Additional CSS classes for the title element.
+
+class-footer
+: Additional CSS classes for the footer element.

docs/conf.py

@@ -11,7 +11,7 @@
 html_title = f"Sphinx Design ({html_theme})"
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-myst_enable_extensions = ["colon_fence", "substitution"]
+myst_enable_extensions = ["colon_fence", "deflist", "substitution"]
 
 myst_substitutions = {
     "loremipsum": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. "

docs/dropdowns.md

@@ -0,0 +1,41 @@
+(dropdowns)=
+
+# Dropdowns
+
+:::{dropdown} Dropdown title
+Dropdown content
+:::
+
+:::{dropdown}
+Dropdown content
+:::
+
+::::{dropdown} Parent dropdown title (open by default)
+:open:
+
+:::{dropdown} Child dropdown title
+:color: warning
+:icon: alert
+
+Dropdown content
+:::
+::::
+
+## Dropdowns in a grid
+
+:::::{grid} 1 1 2 2
+:gutter: 1
+
+::::{grid-item}
+:::{dropdown} Dropdown title
+Dropdown content
+:::
+::::
+
+::::{grid-item}
+:::{dropdown} Dropdown title
+Dropdown content
+:::
+::::
+
+:::::