Sphinx Design

0.7.0 · active · verified Thu Apr 09

Sphinx Design is a Sphinx extension that provides a rich set of directives and roles for creating modern, responsive, and visually appealing web components within your documentation. It offers features like cards, grids, dropdowns, tabs, and icon support. The library is actively maintained with frequent updates, often aligning with new Sphinx and Python releases, ensuring compatibility and introducing new design capabilities.

Warnings

breaking Python version compatibility changes frequently with major `sphinx-design` releases. For example, v0.7.0 dropped support for Python 3.9 and 3.10.
Fix: Always check the `sphinx-design` changelog before upgrading for the required Python version. For v0.7.0, Python >= 3.11 is required.
breaking Sphinx version compatibility is strictly managed. `sphinx-design` often drops support for older Sphinx versions while adding support for newer ones.
Fix: Consult the `sphinx-design` changelog or PyPI `Requires: Sphinx` metadata for the exact Sphinx version range. For v0.7.0, Sphinx v6 support was dropped, implying Sphinx v7+ is expected.
gotcha Icon sets (Material Design Icons, Octicons) are periodically updated, which may change available icons or require updates to existing icon names.
Fix: Refer to the `sphinx-design` documentation for the latest supported icon names and categories if icons appear broken or are not found after an upgrade.
gotcha The `sd_custom_directives` configuration option, allowing definition of custom directives with default options, was introduced in v0.6.0. Users on older versions cannot use this feature.
Fix: Upgrade to `sphinx-design` v0.6.0 or newer to utilize the `sd_custom_directives` feature for advanced customization of directives.

Install

pip install sphinx-design Install latest version

Imports

sphinx_design
```
extensions = ['sphinx_design']
```
sphinx-design is enabled by adding its module name to the 'extensions' list in your Sphinx project's conf.py, not via a direct Python 'import' statement.

Quickstart

To quickly enable `sphinx-design`, add `'sphinx_design'` to your `extensions` list in `conf.py`. After that, you can use its directives and roles (like `dropdown`, `card`, `grid`, `sd-icon`) directly in your reStructuredText or MyST Markdown files. The example demonstrates generating a `conf.py` and provides commented guidance for using directives in content files.

import os

def create_minimal_conf_py():
    conf_content = '''
project = 'My Design Docs'
copyright = '2023, Author'
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx_design'
]
html_theme = 'furo'
'''
    with open('conf.py', 'w') as f:
        f.write(conf_content)

    # In a real scenario, you'd then create an index.rst or index.md like this:
    # with open('index.rst', 'w') as f:
    #     f.write('''
    # My Design Docs
    # ==============
    #
    # .. dropdown:: Click Me!
    #    :color: primary
    #
    #    This is a dropdown content block.
    #
    # .. card:: Feature Card
    #    :shadow: lg
    #    :text-align: center
    #
    #    A simple card to highlight information.
    #
    #    :::{link-button} https://example.com
    #    Visit Example
    #    :::
    # ''')

    print("Generated conf.py with sphinx_design extension enabled.")
    print("To use directives, add them to your .rst or .md files (e.g., dropdown, card, grid).")

if __name__ == '__main__':
    create_minimal_conf_py()

view raw JSON →