📚 DOCS: Add development guide

Author: chrisjsewell

README.md

@@ -39,24 +39,17 @@ View the documentation in multiple themes:
 
 ## Comparison to sphinx-panels
 
-This package is an iteration on sphinx-panels and intends to replace it.
-
-- Replaces `panel` directive with top-level `grid` + children `grid-item-card`
-  - less "bespoke" syntax
-  - `grid-item` can be used when no card is needed
-  - `card` can be used independently of grids
-- tabs changed:
-  - top-level `tab-set`
-  - `tabbed` -> `tab-item`
-  - include `:sync:` option to synchronize tab selection across sets
-- Minimises direct use of CSS classes (encourage to not use them)
-  - More declarative, easy to understand options, easier to validate
-  - Easier to work with non-HTML outputs
-  - Easier to improve/refactor
-- Updated Bootstrap CSS v4 -> v5
-  - top-level grid can define both column numbers and gutter sizes
-- All CSS classes are prefixed with `sd-` (no clash with other theme/extension CSS)
-- All colors use CSS variables (customisable)
+This package is an iteration on [sphinx-panels](https://github.com/executablebooks/sphinx-panels) and intends to replace it.
+See [Migrating from sphinx-panels](./docs/get_started.md) for more information.
+
+## Development
+
+It is recommended to use [tox](https://tox.readthedocs.io/en/latest/) to run the tests and document builds.
+Run `tox -va` to see all the available tox environments.
+
+To run linting, formatting and SASS compilation, use [pre-commit](https://pre-commit.com/).
+`pre-commit run --all css` will run the SASS compiler, for which you will need [node](https://nodejs.org) and [npm](https://www.npmjs.com/) installed,
+or you can directly run `npm run css`.
 
 ## TODO
 

docs/get_started.md

@@ -53,3 +53,51 @@ sd_hide_title: true
 - Explorer >= 12
 
 (Mirrors: <https://github.com/twbs/bootstrap/blob/v5.0.2/.browserslistrc>)
+
+## Migrating from sphinx-panels
+
+This package arose as an iteration on [sphinx-panels](https://github.com/executablebooks/sphinx-panels), with the intention to make it more flexible, easier to use, and minimise CSS clashes wth sphinx themes.
+
+Notable changes:
+
+### Reduce direct use of CSS classes
+
+These are replaced by the use of directive options, which are:
+
+- Easier to understand
+- Easier to validate
+- Easier to work with non-HTML outputs
+- Easier to improve/refactor
+
+### `panel` directive replaced
+
+The `panel` directive is replaced by the use of the top-level `grid` directive,
+then using `grid-item-card` directive children, rather than delimiting cards by `---`.
+
+If no card is needed, then the `grid-item` directive can be used instead
+and `card` can be also used independently of grids.
+
+### `tabbed` directive replaced
+
+The `tabbed` directive is replaced by the use of the top-level `tab-set` directive,
+then using `tab-item` directive children.
+
+The `:sync:` option allows to synchronize tab selection across sets.
+
+The `tab-set-code` directive provides a shorthand for synced code examples.
+
+### `octicon` icon role
+
+The default SVGs produced are now sized relative to the surrounding text (i.e. using `1em`).
+The syntax for specifying a custom size and adding classes is also changed.
+
+This is similar for favicon icons.
+
+### Improved CSS
+
+Updated Bootstrap CSS from v4 -> v5,
+which in particular allows top-level grid to define both column numbers and gutter sizes.
+
+All CSS classes are prefixed with `sd-` (no clash with other theme/extension CSS)
+
+All colors use CSS variables (customisable)

setup.cfg

@@ -57,7 +57,7 @@ theme_pydata =
 theme_rtd =
     sphinx-rtd-theme~=0.5.0
 theme_sbt =
-    sphinx-book-theme~=0.1.1
+    sphinx-book-theme~=0.1.2
 
 [mypy]
 show_error_codes = True

tox.ini

@@ -10,6 +10,7 @@ envlist = py38
 usedevelop = true
 
 [testenv:py{36,37,38,39}]
+description = Run unit tests with this Python version
 extras =
     testing
 deps =
@@ -19,6 +20,9 @@ deps =
 commands = pytest {posargs}
 
 [testenv:docs-{update,clean}-{alabaster,rtd,pydata,sbt,furo}]
+description =
+    clean: Run documentation build for this theme (removing existing builds)
+    update: Run documentation build for this theme (reusing existing builds)
 extras =
     rtd
     rtd: theme_rtd
@@ -41,6 +45,7 @@ commands =
 commands_post = echo "open docs/_build/{posargs:html}/index.html"
 
 [testenv:docs-live-{alabaster,rtd,pydata,sbt,furo}]
+description = Start documentation autobuild for this theme
 extras =
     rtd
     rtd: theme_rtd