Sphinx Panels

Common errors

• WARNING: Unknown directive type "panel".

  cause The `sphinx_panels` extension has not been enabled in your Sphinx project's `conf.py` file.
  fix Add `'sphinx_panels'` to the `extensions` list in your Sphinx `conf.py` file.

• Invalid option block for 'grid' directive: not a block sequence. (or similar for syntax errors)

  cause Incorrect option syntax for a `grid`, `panel`, or other `sphinx-panels` directive, especially if migrating from older versions (pre-0.3.0).
  fix Check the official `sphinx-panels` documentation for the correct option syntax for your version. Ensure options are correctly indented and formatted (e.g., `key: value` for structured options).

• Panels are not rendering correctly, appearing unstyled, or stacking vertically instead of in a grid.

  cause The CSS files for `sphinx-panels` might not be loading correctly, or there are significant CSS conflicts with your chosen Sphinx theme.
  fix Verify that `sphinx-panels` is correctly enabled in `conf.py`. Use your browser's developer tools to check if `sphinx-panels` CSS files are being loaded and if there are any console errors related to CSS. If theme conflicts are suspected, consider adding custom CSS overrides or testing with a default theme like `alabaster` or `furo`.

Warnings

• breaking Prior to v0.2.0, sphinx-panels underwent a 'Major Revamp'. The CSS classes and internal structure for panels were significantly different. Existing `.. panel::` directives or custom CSS relying on pre-0.2.0 structure may break.
  Fix: Consult the v0.2.0 changelog and updated documentation for the new class structure and directive options. Re-evaluate and update any custom CSS or directive usage.
• breaking In v0.3.0, the option syntax for directives like `.. panel::` or `.. grid::` was improved. Older, less explicit syntax might no longer be parsed correctly, leading to build failures or incorrect rendering.
  Fix: Update directive options to follow the new, more explicit syntax as shown in the latest documentation. For example, options might require a `key: value` format instead of just a bare `key`.
• gotcha Some Sphinx themes may have CSS rules that conflict with `sphinx-panels`, especially regarding button styling or general layout, leading to unexpected rendering or overridden styles.
  Fix: If panels are not rendering as expected, use browser developer tools to inspect the generated HTML and CSS. Look for conflicting styles and consider adding custom CSS in your `_static/custom.css` to override them, or experiment with a different Sphinx theme.

Install

• pip install sphinx-panels Install latest version

Imports

• Extension activation
  wrong:

  from sphinx_panels import ...

  correct:

  extensions = ['sphinx_panels']

  Sphinx extensions are activated by adding their name to the `extensions` list in `conf.py`, not by importing Python modules directly into your project's code.

Quickstart

To use sphinx-panels, first enable it in your Sphinx project's `conf.py` file by adding 'sphinx_panels' to the `extensions` list. Then, you can use directives like `.. grid::` or `.. panel::` in your reStructuredText or MyST Markdown files.

# conf.py
project = 'My Panel Project'
copyright = '2024, Your Name'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx_panels' # Enable the extension
]

html_theme = 'alabaster'

# example.rst (or .md if using MyST)
# .. grid:: 1 2 2 3
#    :gutter: 2
#
#    .. grid-item-card:: Card Title 1
#       :shadow: sm
#
#       This is the content for the first card.
#
#    .. grid-item-card:: Card Title 2
#       :shadow: sm
#
#       This is the content for the second card.
#
#    .. grid-item-card:: Card Title 3
#       :shadow: sm
#
#       This is the content for the third card.