Sphinx design

This example shows how the Ansys Sphinx Theme renders documentation components using the sphinx-design extension. For comprehensive information, see its documentation.

Credits and acknowledgments

The examples presented below are sourced from the Sphinx Design project Copyright (c) by Chris Sewell (2023), available at sphinx design examples. This project is licensed under the MIT License.

Badge-basic

:bdg:`plain badge`

:bdg-primary:`primary`, :bdg-primary-line:`primary-line`

:bdg-secondary:`secondary`, :bdg-secondary-line:`secondary-line`

:bdg-success:`success`, :bdg-success-line:`success-line`

:bdg-info:`info`, :bdg-info-line:`info-line`

:bdg-warning:`warning`, :bdg-warning-line:`warning-line`

:bdg-danger:`danger`, :bdg-danger-line:`danger-line`

:bdg-light:`light`, :bdg-light-line:`light-line`

:bdg-muted:`muted`, :bdg-muted-line:`muted-line`

:bdg-dark:`dark`, :bdg-dark-line:`dark-line`

:bdg-white:`white`, :bdg-white-line:`white-line`

:bdg-black:`black`, :bdg-black-line:`black-line`

This directive renders as follows:

plain badge

primary, primary-line

secondary, secondary-line

success, success-line

info, info-line

warning, warning-line

danger, danger-line

light, light-line

muted, muted-line

dark, dark-line

white, white-line

black, black-line

Badge-link

:bdg-link-primary:`https://example.com`

:bdg-link-primary-line:`explicit title <https://example.com>`

This directive renders as follows:

https://example.com

explicit title

Button-link

.. button-link:: https://example.com

.. button-link:: https://example.com

    Button text

.. button-link:: https://example.com
    :color: primary
    :shadow:

.. button-link:: https://example.com
    :color: primary
    :outline:

.. button-link:: https://example.com
    :color: secondary
    :expand:

This directive renders as follows:

https://example.com

Button text

https://example.com

https://example.com

https://example.com

Card-basic

.. card:: Card Title

    Card content

This directive renders as follows:

Card Title

Card content

Card-carousel

.. card-carousel:: 2

    .. card:: card 1

        content

    .. card:: card 2

        Longer

        content

    .. card:: card 3

    .. card:: card 4

    .. card:: card 5

    .. card:: card 6

This directive renders as follows:

card 1

content

card 2

Longer

content

card 3

card 4

card 5

card 6

Card-head-foot

.. card:: Card Title

    Header
    ^^^
    Card content
    +++
    Footer

This directive renders as follows:

Header

Card Title

Card content

Footer

Card-images

.. grid:: 2 3 3 4

    .. grid-item::

        .. card:: Title
            :img-background: images/particle_background.jpg
            :class-card: sd-text-black
            :img-alt: my text

            Text

    .. grid-item-card:: Title
        :img-top: images/particle_background.jpg
        :img-alt:

        Header
        ^^^
        Content
        +++
        Footer

    .. grid-item-card:: Title
        :img-bottom: images/particle_background.jpg

        Header
        ^^^
        Content
        +++
        Footer

This directive renders as follows:

Title

Text

Header

Title

Content

Footer

Header

Title

Content

Footer

Card-link

.. _cards-clickable:

Clickable cards
...............

Using the ``link`` and ``link-type`` options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:

.. card:: Clickable Card (external)
    :link: https://example.com

    The entire card can be clicked to navigate to https://example.com.

.. card:: Clickable Card (external)
    :link: https://example.com
    :link-alt: example.com

    The entire card can be clicked to navigate to https://example.com.

.. card:: Clickable Card (internal)
    :link: cards-clickable
    :link-type: ref

    The entire card can be clicked to navigate to the ``cards-clickable`` reference card-link.txt.

.. 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 card-link.txt.

This directive renders as follows:

Clickable cards

Using the link and link-type options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:

Clickable Card (external)

The entire card can be clicked to navigate to https://example.com.

https://example.com

Clickable Card (external)

The entire card can be clicked to navigate to https://example.com.

example.com

Clickable Card (internal)

The entire card can be clicked to navigate to the cards-clickable reference card-link.txt.

Clickable cards

Clickable Card (internal)

The entire card can be clicked to navigate to the cards-clickable reference card-link.txt.

clickable cards

Card-title-link

.. _card-title-link.txt:
.. card:: Card Title https://example.com :ref:`link <card-title-link.txt>`

    Card content

This directive renders as follows:

Card Title https://example.com link

Card content

Div-basic

.. div:: sd-text-center sd-font-italic sd-text-primary

    Some CSS styled text

This directive renders as follows:

Some CSS styled text

Dropdown-basic

.. dropdown::

    Dropdown content

.. dropdown:: Dropdown title

    Dropdown content

.. dropdown:: Open dropdown
    :open:

    Dropdown content

This directive renders as follows:

Dropdown content

Dropdown title

Dropdown content

Open dropdown

Dropdown content

Dropdown-options

.. dropdown:: Title
    :name: dropdown-options.txt
    :color: info
    :icon: alert
    :margin: 1
    :class-container: class-container
    :class-title: class-title
    :class-body: class-body

    Dropdown content

:ref:`dropdown-options.txt`, :ref:`text <dropdown-options.txt>`

This directive renders as follows:

Title

Dropdown content

Title, text

Grid-basic

.. grid:: 1 2 3 4
    :outline:

    .. grid-item::

        A

    .. grid-item::

        B

    .. grid-item::

        C

    .. grid-item::

        D

This directive renders as follows:

A

B

C

D

Grid-card-columns

.. grid:: 2

    .. grid-item-card::
        :columns: auto

        A

    .. grid-item-card::
        :columns: 12 6 6 6

        B

    .. grid-item-card::
        :columns: 12

        C

This directive renders as follows:

A

B

C

Grid-card

.. grid:: 2

    .. grid-item-card::  Title 1

        A

    .. grid-item-card::  Title 2

        B

This directive renders as follows:

Title 1

A

Title 2

B

Grid-gutter

.. grid:: 2
    :gutter: 1

    .. grid-item-card::

        A

    .. grid-item-card::

        B

.. grid:: 2
    :gutter: 3 3 4 5

    .. grid-item-card::

        A

    .. grid-item-card::

        B

This directive renders as follows:

A

B

A

B

Grid-nested

.. 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

This directive renders as follows:

Item 1.1

Multi-line

content

Item 1.2

Content

Item 2.1

Content

Item 2.2

Content

Item 2.3

Content

Icon-fontawesome

An icon :fas:`spinner;sd-bg-primary sd-bg-text-primary`, some more text.

This directive renders as follows:

An icon , some more text.

Icon-material-design

- 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.

This directive renders as follows:

• A regular icon: , some more text

• A coloured regular icon: , some more text.

• A coloured outline icon: , some more text.

• A coloured sharp icon: , some more text.

• A coloured round icon: , some more text.

• A coloured two-tone icon: , some more text.

• A fixed size icon: , some more text.

Icon-octicon

A coloured icon: :octicon:`report;1em;sd-text-info`, some more text.

This directive renders as follows:

A coloured icon: , some more text.

Tab-basic

.. tab-set::

    .. tab-item:: Label1

        Content 1

    .. tab-item:: Label2

        Content 2

This directive renders as follows:

Label1

Content 1

Label2

Content 2

Tab-code-set

.. tab-set-code::

    .. literalinclude:: ./snippet.py
        :language: python

    .. code-block:: javascript

        a = 1;

This directive renders as follows:

PYTHON

# Copyright (C) 2021 - 2024 ANSYS, Inc. and/or its affiliates.
# SPDX-License-Identifier: MIT
#
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

"""Sample functions for ansys-sphinx-theme."""


def func(arg1, arg2):
    """Summary line <should be one one line>.

    Extended description of function.  Can span multiple lines and
    provides a general overview of the function.

    .. warning::
       Use the ``.. warning::`` directive within the doc-string for any
       warnings you would like to explicitly state.  For example, if
       this method will be deprecated in the next release.

    Parameters
    ----------
    arg1 : int
        Description of arg1.
    arg2 : str
        Description of arg2.

    Returns
    -------
    bool
        Description of return value.

    Examples
    --------
    >>> func(1, "foo")
    True

    """
    return True

JAVASCRIPT

a = 1;

Tab-options

.. tab-set::
    :class: class-set

    .. tab-item:: **Label**
        :name: tab-options.txt
        :selected:
        :class-container: class-container
        :class-label: class-label
        :class-content: class-content

        Content

:ref:`tab-options.txt`, :ref:`text <tab-options.txt>`

This directive renders as follows:

Label

Content

Label, text

Tab-sync

.. tab-set::
    :sync-group: category

    .. tab-item:: Label1
        :sync: key1

        Content 1

    .. tab-item:: Label2
        :sync: key2

        Content 2

.. tab-set::
    :sync-group: category

    .. tab-item:: Label1
        :sync: key1

        Content 1

    .. tab-item:: Label2
        :sync: key2

        Content 2

This directive renders as follows:

Label1

Content 1

Label2

Content 2

Label1

Content 1

Label2

Content 2