DOCSEARCHbyAlgolia
Submit Docs

Awesome Sphinx Theme

website·Indexed 32 days ago

https://sphinxawesome.xyz/

A theme for Sphinx used to create functional and beautiful documentation websites. It provides support for custom CSS, JavaScript, and Jinja2 templates, and integrates with extensions such as myst-nb and sphinx-design. The theme includes styles for code blocks, Jupyter notebooks, equations, and auto-generated API documentation.

Tokens
6.9K
Snippets
56
Records
73
Agent score
62%

What's inside Awesome Sphinx Theme

  1. Alert users with Warnings, Cautions, and Important callouts

    Use the warning, important, attention, or caution directives to alert users about important issues. These four directives all render in the same visual style.
    .. warning::
   This is a warning.

.. caution::
   This is how a caution appears.

  2. Use Sphinx Awesome theme with the myst-nb extension

    The Sphinx Awesome theme is compatible with the myst-nb extension for rendering Jupyter notebooks. It supports the display of code cells alongside their corresponding outputs, including standard print statements, expression results (returned values), and full error tracebacks (e.g., ZeroDivisionError).

  3. Integrate sphinx-design components with Awesome Theme

    The sphinx-design extension provides a set of visual components (Cards, Grids, Dropdowns, Tabs, Badges, and Buttons). When using the Awesome Theme, the theme automatically detects the sphinx-design extension and applies additional CSS styles to enhance the visual appearance of these components.

  4. Highlight critical issues with Error and Danger callouts

    Use the error or danger directives to inform users about errors or potentially dangerous steps. Both directives render in the same style.
    .. error::
   This is how an error appears.

.. danger::
   This is how a potentially dangerous step appears.

  5. Use Block Quotations for highlights

    Use standard block quotation syntax to highlight quotes within the documentation.
    > “It is my business to know things. That is my trade.”
> 
> —Sherlock Holmes

  6. Update Python and Sphinx requirements for Awesome Theme v6.0

    Starting with version 6.0, the Awesome Theme requires Python 3.10 or newer and provides support for Sphinx 9. Support for Python 3.8 and 3.9 has been dropped.

  7. Embed images without captions in Sphinx

    Use the image directive for images that do not require captions or legends. You can control the horizontal placement using the :align: option with values such as center or right.
    .. image:: path/to/image.svg
   :align: center

  8. Override template blocks for custom page content

    You can inject custom code into specific areas of the page by extending page.html and overriding the following blocks:

    • extrahead: Injected before the closing </head> tag (ideal for custom CSS or JS).
    • body_before: Adds content to the top of the page.
    • body_after: Adds content to the bottom of the page.
    {% extends "!page.html" %}

{{ super() }}

{% block extrahead %}
{# Included before the closing </head> tag #}
{% endblock %}

{% block extrabody %}
{# Included after the main content, before the <footer> #}
{% endblock %}

  9. Create figures with captions and legends in Sphinx

    Use the figure directive when an image requires a caption or a legend. Captions are added as text immediately following the image within the directive. Legends can be added using the :legend: option. Alignment is controlled via the :align: option (e.g., center, right).
    .. figure:: path/to/image.svg
   :align: center
   :legend: Image source attribution

   This is the image caption.

  10. Set up a local development environment for a custom theme

    To build a custom theme by modifying templates or CSS, you need to set up the development environment. The recommended tool for managing dependencies is mise. The process involves cloning the repository, installing Python dependencies via mise or hatch, and installing JavaScript dependencies via pnpm within the theme source directory.
    # 1. Install Python dependencies
mise install

# 2. Verify environment with linting and type checking
hatch run lint:all

# 3. Install JS dependencies
cd src/theme-src
pnpm install

# 4. Build JS and CSS assets
pnpm build

  11. Create positive callouts with Tips and Hints

    Use the tip or hint directives to highlight information that provides a positive effect for users, such as shortcuts or confirmations. Both directives render in the same style.
    .. tip::
   This is how a tip appears.

.. hint::
   Hints and tips appear in the same style.

  12. Document command-line options using the Sphinx option directive

    Use the Sphinx option directive to document command-line flags. This method renders each option as a distinct element and automatically generates permalinks for every option, making them individually linkable within the documentation.
    .. option:: -h, --help
   Display a (hopefully) useful message.

.. option:: -i FILE, --input FILE
   Specify an input file.

.. option:: -v, --verbose
   Increase the verbosity.