Shibuya Sphinx Theme

Shibuya is a modern, responsive, and customizable theme for the Sphinx documentation generator. Key features include:

• Responsive Layout: Optimized for all devices from desktops to smartphones.
• Light/Dark Mode: Support for user-selectable themes.
• Customizable Colors: Uses radix colors for branding.
• Jupyter Integration: Enhanced CSS/UI support for Jupyter-related extensions (e.g., nbsphinx).
• Multiple Layouts: Options for landing pages, simple one-page layouts, and three-column documentation pages.

If you prefer an alternative to the Shibuya theme for your Sphinx documentation, the following themes are recommended:

• Furo: A clean, responsive theme featuring a two-column layout.
• Material for Sphinx: An adaptation of the popular mkdocs-material theme for Sphinx.
• PyData: A clean, Bootstrap-based theme developed by the PyData community.
• Read the Docs: The standard theme used by the Read the Docs hosting service.

The click-extra extension provides Sphinx directives to document and run Click-based commands within your documentation:

• .. click:example::: Used to define a Python code block containing Click commands (using decorators like @extra_command, @option, etc.) that should be processed.
• .. click:run::: Used to execute and display the output of a specific command defined in a preceding click:example block using invoke(function_name, args=[...]).

.. click:example::

    from click_extra import extra_command, option

    @extra_command
    @option("--name")
    def hello(name):
        print(f"Hello {name}")

.. click:run::

    invoke(hello, args=["--name", "World"])

You can nest admonitions inside one another by indenting the inner directive. While supported, nesting multiple levels (e.g., a danger inside a warning inside a note) can become visually distracting and confusing for readers.

.. note::
   An admonition can contain another admonition.

   .. warning::
      Nested warning content.

To change the appearance of specific structural elements, Shibuya provides partial templates that you can customize. These templates allow you to override or modify the following sections:

• Header
• Footer
• Navbar
• Sidebar (including elements like Table of Contents, advertisements, or 'Edit this page' links)

You can also customize typography using Web Fonts and visual elements using custom Icons.

The Shibuya theme provides a surface class that can be applied to a grid or its container to create a specific visual style for grid cards.

.. grid:: 1 1 2 3
    :class-row: surface

    .. grid-item-card:: Card Title
        Content

The Shibuya Theme uses a fixed three-part layout designed for professional documentation. Understanding this structure helps when customizing or planning content placement:

• header: Compatible with most company or product homepages.
• body: Contains a left sidebar for document links, the main content area, and a right sidebar for the table of contents.
• footer: Reserved for additional information and links about your company or product.

For code that is computationally expensive, non-deterministic, or requires restricted resources, you should avoid executing it during every build. Instead, manually pair the input and the expected output using these two directives:

1. .. jupyter-input::: Contains the source code (does not execute).
2. .. jupyter-output::: Contains the pre-computed output text.

This approach provides the visual appearance of an executed cell without the build-time cost.

.. jupyter-input::
    :linenos:

    def slow_function():
        return "done"
    print(slow_function())

.. jupyter-output::
    done

When using the Shibuya theme, you can render an outline style for tab-sets by adding the :class: outline option to the .. tab-set:: directive.

.. tab-set::
    :class: outline

    .. tab-item:: Label
        Content

Shibuya uses a structured naming convention for its CSS variables to make customization predictable. All Shibuya-specific variables follow this pattern:

1. Prefix: --sy (stands for Shibuya).
2. Segment: A dash followed by a category indicator:
   • -c: Color
   • -s: Size
   • -f: Font
3. Specificity: A descriptive name for the specific element (e.g., --sy-c-link for link color).

This allows you to easily identify whether a variable controls color, size, or typography.

In reStructuredText, a block quote is created by indenting a text block relative to the preceding text without using specific markup.

To include an attribution, start a new line within the indented block with --, ---, or an em-dash, flush left within the block quote. If the attribution spans multiple lines, ensure the left edges of subsequent lines align.

Important: When nesting block quotes inside other structures like lists, use an empty comment (..) to separate them. Otherwise, the quote content will be treated as part of the preceding list item.

This is an ordinary paragraph, introducing a block quote.

    "It is my business to know things.  That is my trade."

    -- Sherlock Holmes