### Sphinx Extension Setup Structure Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Outlines the hierarchical structure of the Sphinx extension setup process, starting from `setup()` in `__init__.py` and branching out to various `setup_` functions for different component types. ```text setup() in __init__.py └── setup_extension() in extension.py ├── setup_badges_and_buttons() ├── setup_cards() ├── setup_grids() ├── setup_dropdown() ├── setup_icons() ├── setup_tabs() └── setup_article_info() ``` -------------------------------- ### Python Docstring Example Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Example of a Python docstring for a function creating a component node. Includes type hints and parameter descriptions. ```python def create_component( name: str, rawtext: str, *, classes: Sequence[str] = (), ) -> nodes.container: """Create a component container node. :param name: The component name. :param rawtext: The raw text content. :param classes: Additional CSS classes to apply. :return: A container node with the component. """ ... ``` -------------------------------- ### Run all tests with Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Execute all tests for the project using the default Python version. Ensure Tox is installed and configured. ```bash tox ``` -------------------------------- ### Pytest Example for Sphinx Builder Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Demonstrates how to write a pytest test using the `sphinx_builder` and `file_regression` fixtures. It creates a Sphinx project, adds content with a grid directive, builds the project, and checks the output. ```python def test_grid_basic(sphinx_builder, file_regression): builder = sphinx_builder() builder.src_path.joinpath("index.md").write_text( """ # Test ````{grid} 2 :gutter: 1 ```{grid-item} Item 1 ``` ```{grid-item} Item 2 ``` ```` """, encoding="utf8", ) builder.build() doctree = builder.get_doctree("index") file_regression.check(doctree.pformat(), extension=".xml") ``` -------------------------------- ### Border Thickness Class Example Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/css_classes.md Apply a border with a thickness of 5 to an element using the `sd-border-5` class. ```css `sd-border-5` ``` -------------------------------- ### Display a Colored Sharp Material Design Icon Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/badges_buttons.md This example demonstrates how to display a colored sharp Material Design icon. It utilizes the `sd-material-icon` class, the specific icon class, and a text color utility class. ```html ``` -------------------------------- ### Display a Colored Outline Material Design Icon Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/badges_buttons.md This example shows how to display a colored outline Material Design icon. It uses the `sd-material-icon` class, the icon class, and a text color utility class. ```html ``` -------------------------------- ### Article Info Directive Read Time Substitution Example Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/additional.md Shows how to use substitutions for the `read-time` option in the `article-info` directive, enabling dynamic calculation or insertion of reading time. ```markdown :read-time: "{sub-ref}`wordcount-minutes` min read" ``` -------------------------------- ### Configure Custom Directives Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/get_started.md Define custom directives with default options in conf.py using 'sd_custom_directives'. This example adds a 'dropdown-syntax' directive inheriting from 'dropdown'. ```python sd_custom_directives = { "dropdown-syntax": { "inherit": "dropdown", "argument": "Syntax", "options": { "color": "primary", "icon": "code", }, } } ``` -------------------------------- ### Commit Message Format Example Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Illustrates the required format for commit messages, including an emoji, keyword, summary, and optional detailed explanation. Keywords are provided for different types of changes. ```text : Summarize in 72 chars or less (#) Optional detailed explanation. ``` -------------------------------- ### Install and Configure sphinx-design Source: https://context7.com/executablebooks/sphinx-design/llms.txt Add 'sphinx_design' to your Sphinx project's extensions in conf.py. For MyST Markdown, also enable 'myst_parser' and 'colon_fence'. ```python # conf.py – minimal setup extensions = ["sphinx_design"] ``` ```python # conf.py – with MyST Parser (recommended for Markdown projects) extensions = ["myst_parser", "sphinx_design"] myst_enable_extensions = ["colon_fence"] ``` ```python # Hide a page title (add to individual page front-matter or RST field list) # MyST: sd_hide_title: true # RST: :sd_hide_title: ``` ```python # Create custom directive aliases with pre-set default options (added in 0.6.0) sd_custom_directives = { "dropdown-syntax": { "inherit": "dropdown", "argument": "Syntax", # default title "options": { "color": "primary", "icon": "code", }, } } ``` ```python # Enable FontAwesome icons in LaTeX output (default: False) sd_fontawesome_latex = False ``` -------------------------------- ### Article Info Directive Date Substitution Example Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/additional.md Demonstrates how to use substitutions for the `date` option within the `article-info` directive. This allows for dynamic date insertion. ```markdown :date: "{sub-ref}`today`" ``` -------------------------------- ### Tabbed Code Examples in Markdown Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/tabs.md Use `tab-set-code` for synchronized code examples. Tabs are labeled by the `language` attribute of directives like `literalinclude` or `code-block`. This requires JavaScript. ```markdown ````{tab-set-code} ```{literalinclude} :language: python ``` ```{code-block} a = 1; ``` ```` ``` -------------------------------- ### Tabbed Code Examples in reStructuredText Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/tabs.md Use `.. tab-set-code::` for synchronized code examples. Tabs are labeled by the `language` attribute of directives like `.. literalinclude::` or `.. code-block::`. This requires JavaScript. ```rst .. tab-set-code:: .. literalinclude:: ./snippet.py :language: python .. code-block:: javascript a = 1; ``` -------------------------------- ### Rounded Border Class Example Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/css_classes.md Apply a rounded border with a radius of 0 to an element using the `sd-rounded-0` class. ```css `sd-rounded-0` ``` -------------------------------- ### Run tests with a specific Python version using Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Execute tests using a specific Python version by specifying the environment. For example, `py311` or `py312`. ```bash tox -e py311 ``` ```bash tox -e py312 ``` -------------------------------- ### Build documentation with different themes using Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Compile the project documentation using various Sphinx themes. Specify the desired theme environment, e.g., `docs-alabaster`. ```bash tox -e docs-alabaster ``` ```bash tox -e docs-rtd ``` ```bash tox -e docs-pydata ``` ```bash tox -e docs-sbt ``` ```bash tox -e docs-furo ``` ```bash tox -e docs-im ``` -------------------------------- ### Basic Dropdown Syntax (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/dropdowns.md Demonstrates the basic syntax for creating dropdowns using Markdown. Content is shown when the header is clicked. ```markdown :::{dropdown} Dropdown content ::: ``` ```markdown :::{dropdown} Dropdown title Dropdown content ::: ``` ```markdown :::{dropdown} Open dropdown :open: Dropdown content ::: ``` -------------------------------- ### Pill Rounded Border Class Example Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/css_classes.md Apply a pill-shaped rounded border to an element using the `sd-rounded-pill` class. ```css `sd-rounded-pill` ``` -------------------------------- ### Clean documentation build with Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Perform a clean build of the documentation by setting the `CLEAN` environment variable to `1` before running the Tox command for the desired theme. ```bash CLEAN=1 tox -e docs-furo ``` -------------------------------- ### Run pre-commit hooks on all files Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Execute all configured pre-commit hooks on every file in the repository to ensure code quality and consistency. ```bash pre-commit run --all-files ``` -------------------------------- ### Basic Dropdown Syntax (RST) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/dropdowns.md Demonstrates the basic syntax for creating dropdowns using reStructuredText. Content is shown when the header is clicked. ```rst .. dropdown:: Dropdown content ``` ```rst .. dropdown:: Dropdown title Dropdown content ``` ```rst .. dropdown:: Open dropdown :open: Dropdown content ``` -------------------------------- ### Basic Grid Layout (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Defines a grid with 1, 2, 3, and 4 columns for different screen sizes respectively. Use this for basic adaptive layouts. ```markdown ::::{grid} 1 2 3 4 :outline: :::{grid-item} A ::: :::{grid-item} B ::: :::{grid-item} C ::: :::{grid-item} D ::: :::: ``` -------------------------------- ### Basic Grid Layout (RST) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Defines a grid with 1, 2, 3, and 4 columns for different screen sizes respectively. Use this for basic adaptive layouts. ```rst .. grid:: 1 2 3 4 :outline: .. grid-item:: A .. grid-item:: B .. grid-item:: C .. grid-item:: D ``` -------------------------------- ### Build documentation with a different builder using Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Compile documentation using a specific Sphinx builder, such as `linkcheck`. Set the `BUILDER` environment variable before running the Tox command. ```bash BUILDER=linkcheck tox -e docs-furo ``` -------------------------------- ### Create a Card with Header, Body, and Footer (RST) Source: https://context7.com/executablebooks/sphinx-design/llms.txt Use the `card` directive in RST to create a flexible content container. Content before `^^^` is the header, after `+++` is the footer, and between is the body. Supports images, links, and custom styling. ```rst .. RST – full-featured card with header, image, body, footer, and link .. card:: Project Alpha :img-top: images/hero.jpg :img-alt: Project hero image :link: project-alpha-details :link-type: ref :link-alt: View project details :shadow: lg :width: 75% :text-align: center :class-card: my-custom-class Optional header content ^^^ Main body text that describes the project. Cards scale gracefully to the available width. +++ Last updated: 2025-01-19 ``` -------------------------------- ### Formatting with Ruff Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Apply code formatting using Ruff. This command ensures consistent code style across the project. ```bash tox -e ruff-fmt ``` -------------------------------- ### Basic Card Syntax (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/cards.md Use this syntax to create a simple card with a title and content in Markdown. ```markdown :::{card} Card Title Card content ::: ``` -------------------------------- ### Create Styled Buttons for Navigation Source: https://context7.com/executablebooks/sphinx-design/llms.txt Use `button-link` for external URLs and `button-ref` for internal references. Options like `color`, `outline`, `expand`, and `shadow` customize button appearance. ```rst .. RST .. button-link:: https://pypi.org/project/sphinx-design :color: primary :shadow: Install from PyPI .. button-link:: https://github.com/executablebooks/sphinx-design :color: secondary :outline: :expand: View on GitHub .. button-ref:: get_started :color: success :ref-type: ref :align: center :tooltip: Jump to the getting-started guide Get Started ``` ```markdown ```{button-link} https://pypi.org/project/sphinx-design :color: primary :shadow: Install from PyPI ``` ```{button-ref} get_started :color: success :ref-type: ref :align: center Get Started ``` ``` -------------------------------- ### Grid with Multiple Gutters (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Defines gutters for small, medium, and large screens (3, 3, 4, 5 units respectively). Adjust spacing based on screen size. ```markdown ::::{grid} 2 :gutter: 3 3 4 5 :::{grid-item-card} A ::: :::{grid-item-card} B ::: :::: ``` -------------------------------- ### Linting with Ruff (auto-fix) Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Run Ruff for linting and automatically fixable issues. The `--fix` flag enables auto-fixing. ```bash tox -e ruff-check -- --fix ``` -------------------------------- ### Responsive Grid Layout (RST) Source: https://context7.com/executablebooks/sphinx-design/llms.txt Use the `grid` directive with `grid-item` directives to create responsive column layouts. Options control gutter, margin, and column distribution across screen sizes. ```rst .. RST – responsive 4-column grid that collapses to 1 column on mobile .. grid:: 1 2 3 4 :gutter: 3 :margin: 2 :outline: .. grid-item:: :columns: 12 6 6 4 :child-align: center Item A .. grid-item:: :columns: 12 6 6 4 Item B .. grid-item:: :columns: 12 12 12 4 Item C ``` -------------------------------- ### Configure Static Path and CSS Files Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/css_variables.md Specify the static path and list custom CSS files to be included in the Sphinx build. This is where you would add your custom.css file to override default styles. ```python html_static_path = ['_static'] html_css_files = ['custom.css'] ``` -------------------------------- ### Nested Grid Layout (RST) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Demonstrates nesting grids within grid items to create complex, multi-level adaptive layouts. Use for intricate page structures. ```rst .. grid:: 1 1 2 2 :gutter: 1 .. grid-item:: .. grid:: 1 1 1 1 :gutter: 1 .. grid-item-card:: Item 1.1 Multi-line content .. grid-item-card:: Item 1.2 Content .. grid-item:: .. grid:: 1 1 1 1 :gutter: 1 .. grid-item-card:: Item 2.1 Content .. grid-item-card:: Item 2.2 Content .. grid-item-card:: Item 2.3 Content ``` -------------------------------- ### Expandable and Clickable Parent Button-Link Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/badges_buttons.md Configure buttons to expand to fit their parent width using the `expand` option. The `click-parent` option makes the entire parent container clickable. ```rst .. button-link:: https://example.com :color: secondary :expand: [https://example.com](https://example.com) ``` -------------------------------- ### Display a Regular Material Design Icon Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/badges_buttons.md Use this to display a standard Material Design icon. Ensure the `sd-material-icon` class and the specific icon class (e.g., `sd-material-icon-data_exploration`) are applied. ```html ``` -------------------------------- ### Create a Card with Header, Body, and Footer (MyST Markdown) Source: https://context7.com/executablebooks/sphinx-design/llms.txt Use the `card` directive in MyST Markdown for a flexible content container. Content before `^^^` is the header, after `+++` is the footer, and between is the body. Supports images, links, and custom styling. ```markdown :::{card} Project Alpha :img-top: images/hero.jpg :link: project-alpha-details :link-type: ref :shadow: lg :width: 75% :text-align: center Optional header content ^^^ Main body text here. +++ Last updated: 2025-01-19 ::: ``` -------------------------------- ### Card with Background Image (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/cards.md Create a card with a background image using the ':img-background:' option. Ensure the image path is correct. ```markdown :::{card} Title :img-background: images/particle_background.jpg :class-card: sd-text-black :img-alt: my text Text ::: ``` -------------------------------- ### Nested Grid Layout (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Demonstrates nesting grids within grid items to create complex, multi-level adaptive layouts. Use for intricate page structures. ```markdown ::::::{grid} 1 1 2 2 :gutter: 1 :::::{grid-item} ::::{grid} 1 1 1 1 :gutter: 1 :::{grid-item-card} Item 1.1 Multi-line content ::: :::{grid-item-card} Item 1.2 Content ::: :::: ::::: :::::{grid-item} ::::{grid} 1 1 1 1 :gutter: 1 :::{grid-item-card} Item 2.1 Content ::: :::{grid-item-card} Item 2.2 Content ::: :::{grid-item-card} Item 2.3 Content ::: :::: ::::: :::::: ``` -------------------------------- ### Create Collapsible Dropdown with Options Source: https://context7.com/executablebooks/sphinx-design/llms.txt Use the `dropdown` directive to create collapsible containers. Options like `open`, `color`, `icon`, and `animate` customize its appearance and behavior. ```rst .. dropdown:: Installation Instructions :open: :color: primary :icon: terminal :animate: fade-in-slide-down :class-body: sd-p-3 Run the following command to install: .. code-block:: bash pip install sphinx-design .. dropdown:: Advanced Options :chevron: down-up :color: warning See :ref:`configuration` for the full list of options. ``` ```markdown :::{dropdown} Installation Instructions :open: :color: primary :icon: terminal :animate: fade-in-slide-down Run the following command: ```bash pip install sphinx-design ``` ::: ``` -------------------------------- ### Create Synchronized Tab Sets (RST) Source: https://context7.com/executablebooks/sphinx-design/llms.txt Use `tab-set` and `tab-item` directives in RST to create tabbed content. The `sync-group` option synchronizes tabs across multiple sets. The `sync` option on `tab-item` allows for cross-set synchronization. ```rst .. RST – two synchronised tab-sets .. tab-set:: :sync-group: lang .. tab-item:: Python :sync: py .. code-block:: python print("Hello, world!") .. tab-item:: JavaScript :sync: js .. code-block:: javascript console.log("Hello, world!"); .. tab-set:: :sync-group: lang .. tab-item:: Python :sync: py :selected: Python is great for data science. .. tab-item:: JavaScript :sync: js JavaScript powers the web. ``` -------------------------------- ### FontAwesome CSS Configuration Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/badges_buttons.md Shows how to include FontAwesome CSS files in Sphinx configuration to enable FontAwesome icon usage. ```python html_css_files = [ "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css" ] ``` -------------------------------- ### Basic Card Syntax (RST) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/cards.md Use this syntax to create a simple card with a title and content in reStructuredText. ```rst .. card:: Card Title Card content ``` -------------------------------- ### Markdown Icon Usage Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/badges_buttons.md Demonstrates how to use different Material Design icon styles (regular, outline, sharp, round, two-tone) with custom sizing and coloring in Markdown. ```markdown - A regular icon: {material-regular}`data_exploration;2em`, some more text - A coloured regular icon: {material-regular}`settings;3em;sd-text-success`, some more text. - A coloured outline icon: {material-outlined}`settings;3em;sd-text-success`, some more text. - A coloured sharp icon: {material-sharp}`settings;3em;sd-text-success`, some more text. - A coloured round icon: {material-round}`settings;3em;sd-text-success`, some more text. - A coloured two-tone icon: {material-twotone}`settings;3em;sd-text-success`, some more text. - A fixed size icon: {material-regular}`data_exploration;24px`, some more text. ``` -------------------------------- ### Clickable Card (External Link - Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/cards.md Make an entire card clickable by specifying an external URL with the ':link:' option. The ':link-alt:' option provides alternative text for the link. ```markdown :::{card} Clickable Card (external) :link: https://example.com The entire card can be clicked to navigate to . ::: ``` ```markdown :::{card} Clickable Card (external) :link: https://example.com :link-alt: example.com The entire card can be clicked to navigate to . ::: ``` -------------------------------- ### Grid with Gutter (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Sets a gutter of 1 unit between grid items. Use this to control spacing for better visual appeal. ```markdown ::::{grid} 2 :gutter: 1 :::{grid-item-card} A ::: :::{grid-item-card} B ::: :::: ``` -------------------------------- ### Basic Badge Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/snippets/myst/badge-basic.txt Use the `bdg` directive for a plain badge. This is the most basic usage. ```myst {bdg}`plain badge` ``` -------------------------------- ### Basic Border Class Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/css_classes.md Apply a basic border with a thickness of 0 to an element using the `sd-border-0` class. ```css `sd-border-0` ``` -------------------------------- ### Display a Colored Regular Material Design Icon Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/badges_buttons.md To display a colored Material Design icon, apply the `sd-material-icon` class, the specific icon class, and a text color utility class (e.g., `sd-text-success`). ```html ``` -------------------------------- ### Create Tabbed Code Blocks (RST) Source: https://context7.com/executablebooks/sphinx-design/llms.txt Use the `tab-set-code` directive in RST as a shorthand for `tab-set` with only code blocks. Each `code-block` becomes a tab, labelled by its language. Tabs are automatically synchronized across the page. ```rst .. RST .. tab-set-code:: .. code-block:: python def greet(name: str) -> str: return f"Hello, {name}!" .. code-block:: javascript function greet(name) { return `Hello, ${name}!`; } .. code-block:: rust fn greet(name: &str) -> String { format!("Hello, {}!", name) } ``` -------------------------------- ### Clickable Card (Internal Link - Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/cards.md Make an entire card clickable by specifying an internal reference target with the ':link:' and ':link-type: ref' options. The ':link-alt:' option provides alternative text for the link. ```markdown :::{card} Clickable Card (internal) :link: cards-clickable :link-type: ref The entire card can be clicked to navigate to the `cards-clickable` reference target. ::: ``` ```markdown :::{card} Clickable Card (internal) :link: cards-clickable :link-type: ref :link-alt: clickable cards The entire card can be clicked to navigate to the `cards-clickable` reference target. ::: ``` -------------------------------- ### Run a specific test file with Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Execute tests within a particular file. Replace `tests/test_snippets.py` with the desired test file path. ```bash tox -- tests/test_snippets.py ``` -------------------------------- ### Card with Header and Footer (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/cards.md Add a header and footer to a card using the '^^^' and '+++' separators in Markdown. ```markdown :::{card} Card Title Header ^^^ Card content +++ Footer ::: ``` -------------------------------- ### Dropdown with Icon Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/dropdowns.md Add an icon to the dropdown header using the `:icon:` option. ```markdown :::{dropdown} Dropdown with icon :icon: star Dropdown content ::: ``` -------------------------------- ### Internal Clickable Card with Alt Text (Reference) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/snippets/myst/card-link.txt Link to an internal reference target and provide custom display text using `:link-alt:`. This enhances clarity for internal navigation. ```myst ::: card:: Clickable Card (internal) :link: cards-clickable :link-type: ref :link-alt: clickable cards The entire card can be clicked to navigate to the `cards-clickable` reference target. ::: ``` -------------------------------- ### Compile SASS to CSS Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Compile SASS source files into CSS. This can be done directly using `npm run css` or through pre-commit hooks. ```bash npm run css ``` ```bash pre-commit run --all css ``` -------------------------------- ### Grid with Cards (Markdown) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Creates a two-column grid where each item is a card with a title. Useful for content that needs distinct visual separation. ```markdown ::::{grid} 2 :::{grid-item-card} Title 1 A ::: :::{grid-item-card} Title 2 B ::: :::: ``` -------------------------------- ### Basic Button-Link Directive Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/badges_buttons.md Use the `button-link` directive to create a simple clickable button linking to a URL. The button text is derived from the content of the directive. ```rst .. button-link:: https://example.com .. button-link:: https://example.com Button text ``` -------------------------------- ### Run tests with coverage using Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Execute all tests and generate a code coverage report. The `--cov=sphinx_design` flag enables coverage tracking for the specified module. ```bash tox -- --cov=sphinx_design ``` -------------------------------- ### Internal Clickable Card (Reference) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/snippets/myst/card-link.txt Create a card that links to an internal reference target using `:link:` and `:link-type: ref`. The card will navigate to the specified reference. ```myst ::: card:: Clickable Card (internal) :link: cards-clickable :link-type: ref The entire card can be clicked to navigate to the `cards-clickable` reference target. ::: ``` -------------------------------- ### Run a specific test function with Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Execute a single test function by specifying its path and name. Adjust `tests/test_snippets.py::test_function_name` accordingly. ```bash tox -- tests/test_snippets.py::test_function_name ``` -------------------------------- ### Create Synchronized Tab Sets (MyST Markdown) Source: https://context7.com/executablebooks/sphinx-design/llms.txt Use `tab-set` and `tab-item` directives in MyST Markdown to create tabbed content. The `sync-group` option synchronizes tabs across multiple sets. The `sync` option on `tab-item` allows for cross-set synchronization. ```markdown ::::{tab-set} :sync-group: lang :::{tab-item} Python :sync: py ```python print("Hello, world!") ``` ::: :::{tab-item} JavaScript :sync: js ```javascript console.log("Hello, world!"); ``` ::: :::: ``` -------------------------------- ### Grid with Multiple Gutters (RST) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Defines gutters for small, medium, and large screens (3, 3, 4, 5 units respectively). Adjust spacing based on screen size. ```rst .. grid:: 2 :gutter: 3 3 4 5 .. grid-item-card:: A .. grid-item-card:: B ``` -------------------------------- ### Basic Tab Set in Markdown Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/tabs.md Use the `tab-set` directive to create a set of tabs. Each `tab-item` defines a tab's label and content. ```markdown ::::{tab-set} :::{tab-item} Label1 Content 1 ::: :::{tab-item} Label2 Content 2 ::: :::: ``` -------------------------------- ### Add sphinx-design to conf.py Source: https://github.com/executablebooks/sphinx-design/blob/main/README.md To use the sphinx-design extension, add it to the extensions list in your Sphinx project's conf.py file. ```python extensions = ["sphinx_design"] ``` -------------------------------- ### Type checking with Mypy Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Perform static type checking on the project using Mypy. This command is executed via Tox with the `mypy` environment. ```bash tox -e mypy ``` -------------------------------- ### Update regression test fixtures using Tox Source: https://github.com/executablebooks/sphinx-design/blob/main/AGENTS.md Regenerate test fixtures for regression testing. Use the `--force-regen` flag to overwrite existing fixtures. ```bash tox -- --force-regen ``` -------------------------------- ### Render Inline Badges with Semantic Colors Source: https://context7.com/executablebooks/sphinx-design/llms.txt Badge roles (`bdg-*`) create small, inline labels. Use `bdg-{color}` for filled, `bdg-{color}-line` for outline, `bdg-link-{color}` for external links, and `bdg-ref-{color}` for internal links. ```rst .. RST Status: :bdg-success:`stable` :bdg-warning-line:`deprecated` Version: :bdg-primary:`v2.0` :bdg-secondary-line:`legacy` External link badge: :bdg-link-info:`PyPI ` Internal reference badge: :bdg-ref-primary:`Getting Started ` ``` ```markdown Status: {bdg-success}`stable` {bdg-warning-line}`deprecated` Version: {bdg-primary}`v2.0` {bdg-secondary-line}`legacy` External link badge: {bdg-link-info}`PyPI ` Internal reference badge: {bdg-ref-primary}`Getting Started ` ``` -------------------------------- ### Grid with Gutter (RST) Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/grids.md Sets a gutter of 1 unit between grid items. Use this to control spacing for better visual appeal. ```rst .. grid:: 2 :gutter: 1 .. grid-item-card:: A .. grid-item-card:: B ``` -------------------------------- ### Create Clickable Cards in reStructuredText Source: https://github.com/executablebooks/sphinx-design/blob/main/docs/cards.md Use the 'link' and 'link-type' options to make entire cards clickable. Specify external URLs or internal references. Note that clickable cards override any other links within them. ```rst .. card:: Clickable Card (external) :link: https://example.com The entire card can be clicked to navigate to https://example.com. ``` ```rst .. card:: Clickable Card (external) :link: https://example.com :link-alt: example.com The entire card can be clicked to navigate to https://example.com. ``` ```rst .. card:: Clickable Card (internal) :link: cards-clickable :link-type: ref The entire card can be clicked to navigate to the ``cards-clickable`` reference target. ``` ```rst .. card:: Clickable Card (internal) :link: cards-clickable :link-type: ref :link-alt: clickable cards The entire card can be clicked to navigate to the ``cards-clickable`` reference target. ```