sphinx-design

A sphinx extension for designing beautiful, view size responsive web components.

Created with inspiration from Bootstrap (v5), Material Design and Material-UI design frameworks.

Usage

Simply pip install sphinx-design and add the extension to your conf.py:

extensions = ["sphinx_design"]

Supported browsers

• Chrome >= 60
• Firefox >= 60
• Firefox ESR
• iOS >= 12
• Safari >= 12
• Explorer >= 12

(Mirrors: https://github.com/twbs/bootstrap/blob/v5.0.2/.browserslistrc)

Theme support

View the documentation in multiple themes:

• alabaster
• sphinx-book-theme
• pydata-sphinx-theme
• sphinx-rtd-theme
• furo

Comparison to sphinx-panels

This package is an iteration on sphinx-panels and intends to replace it. See Migrating from sphinx-panels for more information.

Development

It is recommended to use tox 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. pre-commit run --all css will run the SASS compiler, for which you will need node and npm installed, or you can directly run npm run css.

TODO

• note design goal; to be flexible, but limit the amount of directive nesting required. This factors in to
  • card header/footer syntax? (don't really want to have to use separate directives for these, hence ^^^/+++ syntax)
  • auto-wrap grid-item and tab-item, if not already inside grid or tab-set?

grids items cannot contain headers; is this in anyway possible with docutils structure?

naming of directives/roles: standard prefix?

why are cards setup with "word-wrap: break-word;"?

handle latex

Use autoprefixer when compiling SASS (see https://getbootstrap.com/docs/5.0/getting-started/browsers-devices/#supported-browsers)

horizontal card (grid row inside card, picture on left)

subtitle for card (see https://material.io/components/cards#anatomy)