Improve documentation

Author: amotl

CHANGES.md

@@ -1,4 +1,7 @@
 # Change Log
 
-## v0.0.0 - 2023-07-16
+## v0.1.0 - 2023-07-19
 
+- Add "grid table" element, using directives `sd-table`, `sd-row`, `sd-item`
+- Add "info card" element, using directive `info-card`
+- Add "tag(s)" shortcuts, using roles `tag` and `tags`

README.md

@@ -38,12 +38,13 @@ high-level elements on top.
 
 ## Development
 
-In order to set up the project in development mode, visit the [](#development)
-documentation.
+In order to learn how to set up the project in development mode, please visit the
+[development documentation].
 
 
 
 [Changelog]: https://github.com/panodata/sphinx-design-elements/blob/main/CHANGES.md
+[development documentation]: https://sphinx-design-elements.readthedocs.io/en/latest/sandbox.html
 [Documentation]: https://sphinx-design-elements.readthedocs.io/
 [Issues]: https://github.com/panodata/sphinx-design-elements/issues
 [License]: https://github.com/panodata/sphinx-design-elements/blob/main/LICENSE

docs/get_started.md

@@ -3,19 +3,19 @@
 # Getting Started
 
 ```{article-info}
-:author: "[Panodata Developers](https://github.com/panodata)"
+:author: "[The Panodata Developers](https://github.com/panodata)"
 :date: "{sub-ref}`today`"
 :read-time: "1 min read"
 ```
 
 
 ## Setup
 
-The basic installation supports documentation authoring using the [reStructuredText]
-syntax. You can optionally support the Markdown syntax by enabling the [Markedly
-Structured Text] (MyST) syntax.
+The basic installation supports documentation authoring using the [reStructuredText] (rST)
+syntax. You can optionally support an extended [Markdown] syntax by installing and enabling
+the [Markedly Structured Text] (MyST) extension.
 
-### Setup with reStructuredText
+### Use reStructuredText
 
 Install the package.
 ```shell
@@ -33,7 +33,7 @@ extensions = [
 ```
 
 
-### Setup with Markdown
+### Use Markedly Structured Text
 
 Install the packages.
 ```shell
@@ -76,6 +76,7 @@ would like to share with others, do not hesitate to submit patches, in order to
 add them to the collection.
 
 
+[Markdown]: https://daringfireball.net/projects/markdown/syntax
 [Markedly Structured Text]: https://myst-parser.readthedocs.io/
 [reStructuredText]: https://docutils.sourceforge.io/rst.html
 [Sphinx]: https://www.sphinx-doc.org/

docs/gridtable.md

@@ -7,10 +7,10 @@
 
 _sd-table -- Tables with sphinx{design}_.
 
-A generic, beautiful, yet efficient table element based on a [grid layout](inv:sd#grids),
-with top-down configuration capabilities.
+A beautiful and generic table element based on a [sphinx{design} grid layout](inv:sd#grids),
+with top-down configuration features.
 
-It provides the Sphinx directives `sd-table`, `sd-row`, and `sd-item`,
+It implements the Sphinx directives `sd-table`, `sd-row`, and `sd-item`,
 and a few convenience directive options and flags on them.
 
 
@@ -20,9 +20,9 @@ The idea of this element is to implement a table based on a grid layout, which c
 be parameterized using directives on the table level, so that styling details will
 not clutter the leaf nodes (row and item) too much.
 
-To goal is to provide a table element as an alternative to the `list-table` and
-`csv-table` directives, which explores a few needs of authors not offered by
-other Sphinx directives.
+This grid table element is an alternative to the vanilla `list-table` and `csv-table`
+directive implementations, and as such, explores a few needs of authors not provided
+elsewhere.
 
 
 ## Synopsis
@@ -82,7 +82,13 @@ A few more variants how to change the visual appearance.
 
 ### Visual line separators
 
-Using `:row-class:` to assign row-level styles on the table-level component.
+By using `:row-class:` on the table-level directive, row-level styles can be
+assigned conveniently.
+
+```markdown
+::::{sd-table}
+:row-class: top-border
+```
 
 ::::{sd-table}
 :widths: 3 9

docs/index.md

@@ -38,13 +38,13 @@ Get Started
 
 ::::::
 
-Building upon sphinx-design
+Building upon sphinx{design}
 : [sphinx-design] is a Sphinx extension for designing beautiful, screen-size
   responsive web-components. It is inspired by the [Bootstrap], [Material Design],
-  and [Material-UI] design frameworks, and is the foundation for all composite
-  elements in this collection.
+  and [Material-UI] design frameworks, and uses [CSS Flexible Box Layout], commonly
+  known as [Flexbox]. It is the foundation for all composite elements in this collection.
 
-Works with reStructuredText (rST) and Markedly Structured Text (MyST)
+Works with both reStructuredText (rST) and Markedly Structured Text (MyST)
 : Either write documentation using the venerable [reStructuredText], or use the
   new extended [Markdown]/[CommonMark] syntax [Markedly Structured Text]. Both
   are supported equally well.
@@ -108,11 +108,11 @@ HTML table based on a grid layout, with ergonomic top-down configuration.
 Composite info card container element, to be used as a grid item.
 :::
 
-:::{grid-item-card} {octicon}`plus-circle` Special badges
+:::{grid-item-card} {octicon}`tag` Special badges
 :link: tag
 :link-type: doc
 
-Special {bdg-primary}`badges` and other components.
+Special {tags}`tag-like, badges` and other components.
 :::
 
 ::::
@@ -126,6 +126,8 @@ Kudos to [Chris Sewell] and all contributors for conceiving and maintaining
 [Bootstrap]: https://getbootstrap.com/
 [Chris Sewell]: https://github.com/chrisjsewell
 [CommonMark]: https://spec.commonmark.org/
+[CSS Flexible Box Layout]: https://en.wikipedia.org/wiki/CSS_Flexible_Box_Layout
+[Flexbox]: https://www.w3.org/TR/css-flexbox-1/
 [Markdown]: https://daringfireball.net/projects/markdown/syntax
 [Markedly Structured Text]: https://myst-parser.readthedocs.io/
 [Material Design]: https://material.io

docs/infocard.md

@@ -6,19 +6,15 @@
 ## About
 
 A composite info card container element, to be used as an item within
-a [grid layout](inv:sd#grids). It provides the Sphinx directive `info-card`.
+a [grid layout](inv:sd#grids). It implements the Sphinx directive `info-card`.
 
 
 ## Details
 
-The info card is a composite element offering a title, description text, and
-both verbose and short tags. It is suitable for authoring pages enumerating
-items with dense information, without the maintenance nightmares of tables.
-
-For a compact notation of the short tag elements, it uses the corresponding
-[](#tag-role) for efficiently rendering [](inv:sd#badges), which is also
-provided by this package.
-
+The info card is a composite element based on nested grid and card components
+from [](inv:sd#index). It is suitable to be used as an alternative to tables,
+for example when authoring pages enumerating items with dense information,
+without the maintenance nightmares of tables.
 
 ## Synopsis
 
@@ -49,6 +45,15 @@ and for consolidating them.
 
 ::::
 
+:::{note}
+This example provides a title with link, a formatted description text, and both
+verbose and short tags, represented using badges.
+
+For a compact markup to represent the short tag elements, it uses a shortcut notation
+based on the corresponding [](#tag-role), for efficiently rendering [sphinx{design}
+badges](inv:sd#badges) with a special appearance.
+:::
+
 
 ## Usage
 ````{tab-set-code}
@@ -61,4 +66,6 @@ and for consolidating them.
 ````
 
 
+---
+
 _This page is written in Markedly Structured Text (MyST Markdown)._

docs/sandbox.md

@@ -2,6 +2,8 @@
 
 # Sandbox
 
+
+## Setup
 Those commands will get you started with a sandboxed development environment.
 After invoking `poe check`, and observing the software tests succeed, you
 should be ready to start hacking.
@@ -14,3 +16,41 @@ source .venv/bin/activate
 pip install --editable=.[develop,docs,test]
 poe check
 ```
+
+
+## Software tests
+
+For running the software tests after setup, invoke `poe check`.
+Optionally, activate the virtualenv, if you are coming back to
+development using a fresh terminal session.
+
+```shell
+source .venv/bin/activate
+poe check
+```
+
+
+## Documentation
+
+In order to build the documentation, invoke `poe docs-html`.
+```shell
+poe docs-html
+```
+
+In order to _continuously_ rebuild the documentation, while editing it,
+invoke `poe docs-autobuild`.
+```shell
+poe docs-autobuild
+```
+
+
+## Edit source code
+
+In order to edit or inspect the CSS stylesheet rules, head over to
+[`compiled/style.css`]. For editing or inspecting the directive- and
+role-implementations, see [`gridtable.py`], [`infocard.py`], and [`tag.py`].
+
+[`compiled/style.css`]: https://github.com/panodata/sphinx-design-elements/blob/main/sphinx_design_elements/compiled/style.css
+[`gridtable.py`]: https://github.com/panodata/sphinx-design-elements/blob/main/sphinx_design_elements/gridtable.py
+[`infocard.py`]: https://github.com/panodata/sphinx-design-elements/blob/main/sphinx_design_elements/infocard.py
+[`tag.py`]: https://github.com/panodata/sphinx-design-elements/blob/main/sphinx_design_elements/tag.py

docs/tag.md

@@ -5,24 +5,23 @@
 
 ## About
 
-The `tag` and `tags` roles are shortcuts to the `badge` roles of sphinx{design},
-see [](inv:sd#badges).
+The `tag` and `tags` roles are shortcuts to the `bdg` badge roles of
+[sphinx{design}](inv:sd#index), see [](inv:sd#badges).
 
 
 ## Details
 
-The idea is to need less code for defining "tag"-like badges within the
+The idea is to reduce markup code for defining "tag"-like badges within the
 [](#infocard-directive) element. All of them will use the `outline` option flag
-by default, to give them a corresponding visual appearance.
+by default, to give them a corresponding visual appearance like demonstrated below.
 
-
-## Synopsis
-
-There is the `{tag}`, and the `{tags}` role. A `{tag}` will render its text content
+There are two roles: `{tag}` and `{tags}`. A `{tag}` will render its text content
 1:1 into a single badge element, while `{tags}` will split the text by comma (`,`),
-and renders the outcome using individual badge elements.
+and renders the outcome using multiple badge elements.
 
 
+## Synopsis
+
 ::::{sd-table}
 :widths: 3 3 3 3
 :row-class: top-border