sphinx-panels

A sphinx extension for creating panels in a grid layout or as drop-downs.

  • The panels directive creates panels of content in a grid layout, utilising both the bootstrap 4 grid system, and cards layout.

  • The link-button directive creates a click-able button, linking to a URL or reference, and can also be used to make an entire panel click-able.

  • The dropdown directive creates toggle-able content.

  • opticon and fa roles allow for inline icons to be added.

.. panels::

    Content of the top-left panel

    ---

    Content of the top-right panel

    :badge:`example,badge-primary`

    ---

    .. dropdown:: :fa:`eye,mr-1` Bottom-left panel

        Hidden content

    ---

    .. link-button:: https://example.com
        :text: Clickable Panel
        :classes: stretched-link

Content of the top-left panel

Content of the top-right panel

example

Adaptive Sizing

Try shrinking the size of this window, to see how the panels above realign to compensate for small screens.

Installation

You can install sphinx-panels with pip:

pip install sphinx-panels

Sphinx Configuration

In your conf.py configuration file, simply add sphinx_panels to your extensions list, e.g.:

extensions = [
    ...
    'sphinx_panels'
    ...
]

This extension includes the bootstrap 4 CSS classes relevant to panels. They will be loaded by default but, if you are already using a bootstrap theme, you can disable this by adding panels_add_boostrap_css = False to your conf.py.

You can also change the delimiter regexes used by adding panel_delimiters to your conf.py, e.g. the default value (panels, header, footer) is:

panels_delimiters = (r"^\-{3,}$", r"^\^{3,}$", r"^\+{3,}$")

Panels Usage

Grid Layout

Panels are split by three or more - characters. The layout of panels is then set by using the bootstrap classes. Default classes for all panels may be set in the directive options, then panel specific classes can be added at the start of each panel.

By default the new classes will override those set previously (as defaults or in the top level options), but starting the option value with + will make the classes additive. For example the following options will set the first panel’s card to have both the shadow and bg-info classes:

.. panels::
    :card: shadow

    ---
    :card: + bg-info

See also

The bootstrap 4 grid documentation, and this grid tutorial

Note

The default classes are:

.. panels::
    :container: container pb-4
    :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 p-2
    :card: shadow
.. panels::
    :container: container-lg pb-3
    :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2

    panel1
    ---
    panel2
    ---
    panel3
    ---
    :column: col-lg-12 p-2
    panel4

panel1

panel2

panel3

panel4

Card Layout

Each panel contains a card, which can itself contain a header and/or footer, split by three or more ^^^ and +++ respectively.

See also

The bootstrap 4 card documentation, and this card tutorial

.. panels::

    panel 1 header
    ^^^^^^^^^^^^^^

    panel 1 content

    more content

    ++++++++++++++
    panel 1 footer

    ---

    panel 2 header
    ^^^^^^^^^^^^^^

    panel 2 content

    ++++++++++++++
    panel 2 footer

panel 1 header

panel 1 content

more content

panel 2 header

panel 2 content

Card Styling

To style the look of cards, you may use the directive options to add default CSS classes for each element, or use the per-panel option syntax to add to or override these:

  • container: the top-level container

  • column: the panel container

  • card: the panel card

  • body: the panel card

  • header: the panel header

  • footer: the panel footer

You can add your own CSS (see the html_css_files option) but it is advised you use the built-in bootstrap classes:

  • Card colouring contextual classes: bg-primary, bg-success, bg-info, bg-warning, bg-danger, bg-secondary`, ``bg-dark and bg-light.

  • Padding and margins: border-0, p-2, m-2, —

  • Text alignment: text-justify, text-left, text-center, text-right

.. panels::
    :body: bg-primary text-justify
    :header: text-center
    :footer: text-right

    ---
    :column: + p-1

    panel 1 header
    ^^^^^^^^^^^^^^

    panel 1 content

    ++++++++++++++
    panel 1 footer

    ---
    :column: + p-1 text-center border-0
    :body: bg-info
    :header: bg-success
    :footer: bg-secondary

    panel 2 header
    ^^^^^^^^^^^^^^

    panel 2 content

    ++++++++++++++
    panel 2 footer

panel 1 header

panel 1 content

panel 2 header

panel 2 content

Image Caps

Images can be added to the top and/or bottom of the panel. By default they will expand to fit the width of the card, but classes can also be used to add padding:

.. panels::
    :img-top-cls: pl-5 pr-5

    ---
    :img-top: _static/ebp-logo.png
    :img-bottom: _static/footer-banner.jpg

    header 1
    ^^^^^^^^

    Panel 1 content

    More **content**

    ++++++
    tail 1

    ---
    :img-top: _static/sphinx-logo.png
    :img-top-cls: + bg-success
    :img-bottom: _static/footer-banner.jpg

    header 2
    ^^^^^^^^

    Panel 2 content

    ++++++
    tail 1
img-top

header 1

Panel 1 content

More content

img-bottom
img-top

header 2

Panel 2 content

img-bottom

Inline Icons

Inline icons can be added to your text from either the GitHub octicon or FontAwesome libraries.

rST

Output

:opticon:`report`

:opticon:`x-circle,text-white bg-danger,size=24`

:fa:`save`

:fa:`spinner,text-white bg-primary fa-2x,style=fa`

Note that the theme you are using does not already include the FontAwesome CSS, it should be loaded in your conf.py, with the html_css_files option, e.g.:

html_css_files = ["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"]

By default, icons will only be output in HTML formats. But if you want fontawesome icons to be output on LaTeX, using the fontawesome package, you can add to your conf.py:

panels_add_fontawesome_latex = True

Additional classes can be added after a comma delimiter. Also the size (16px or 24px) can be set for opticons, and the style/prefix for fontawesome (version 5).

Div Directive

The div directive is the same as the container directive, but does not add a container class in HTML outputs, which is incompatible with Bootstrap CSS:

.. div:: text-primary

    hallo

hallo

Combined Example

.. dropdown:: Panels in a drop-down
    :title: bg-success text-warning
    :open:
    :animate: fade-in-slide-down

    .. panels::
        :container: container-fluid pb-1
        :column: col-lg-6 col-md-6 col-sm-12 col-xs-12 p-2
        :card: shadow
        :header: border-0
        :footer: border-0

        ---
        :card: + bg-warning

        header
        ^^^^^^

        Content of the top-left panel

        ++++++
        footer

        ---
        :card: + bg-info
        :footer: + bg-danger

        header
        ^^^^^^

        Content of the top-right panel

        ++++++
        footer

        ---
        :column: col-lg-12 p-3
        :card: + text-center

        .. link-button:: panels/usage
            :type: ref
            :text: Clickable Panel
            :classes: btn-link stretched-link font-weight-bold

Acknowledgements