### Setup Development Environment

Source: https://github.com/jbms/sphinx-immaterial/blob/main/CONTRIBUTING.md

Commands to initialize the project's Python virtual environment and install Node.js dependencies. These steps are required before running build or linting tasks.

```shell
uv sync
```

```shell
npm install
```

--------------------------------

### Install sphinx-immaterial via CLI

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/index.rst

Commands to install the theme package from PyPI or directly from the git source repository.

```bash
pip install sphinx-immaterial
```

```bash
pip install git+https://github.com/jbms/sphinx-immaterial.git
```

--------------------------------

### Install sphinx-immaterial via pip

Source: https://github.com/jbms/sphinx-immaterial/blob/main/README.rst

Commands to install the theme package from PyPI or from a local source directory.

```bash
pip install sphinx-immaterial
```

```bash
pip install -e .
```

--------------------------------

### Install clang-format PyPI Package

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/format_signatures.rst

Installs the clang-format PyPI package as a dependency for ensuring a consistent clang-format version. This is a shell command.

```shell
pip install sphinx-immaterial[clang-format]
```

--------------------------------

### Configure rst-example directive options

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/theme_result.rst

Examples of using the output-prefix and class options within the rst-example directive to customize the presentation of rendered content.

```rst
.. rst-example::
    :class: recursive-rst-example

    .. rst-example::
        :output-prefix: The above code renders the following result:

        The directive content to showcase.
```

--------------------------------

### Create cross-referenceable reStructuredText example

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/theme_result.rst

Demonstrates the use of the rst-example directive to create a block that can be referenced elsewhere in the documentation using the :ref: role. This is useful for linking to specific code blocks or examples.

```rst
.. rst-example::
    :name: ref-this-example

    A :ref:`cross-reference link to this example <ref-this-example>`.
```

--------------------------------

### Install sphinx-immaterial with JSON and validation support

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/json/domain.rst

Installs sphinx-immaterial with both 'json' and 'jsonschema_validation' extra features, enabling JSON schema documentation and validation.

```shell
pip install sphinx-immaterial[json,jsonschema_validation]
```

--------------------------------

### Setup custom layout templates

Source: https://github.com/jbms/sphinx-immaterial/blob/main/README.rst

Commands and template code to override default Jinja blocks for theme customization.

```bash
mkdir source/_templates
touch source/_templates/layout.html
```

```python
templates_path = ['_templates']
```

```jinja
{# Import the theme's layout. #}
{% extends '!layout.html' %}

{%- block extrahead %}
{# Add custom things to the head HTML tag #}
{# Call the parent block #}
{{ super() }}
{%- endblock %}
```

--------------------------------

### Install Sphinx Immaterial with Keys Support

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/keys.rst

This command installs the sphinx-immaterial package with the 'keys' optional feature, which includes the necessary dependencies for the Keys extension. Ensure you have Python and pip installed.

```shell
python -m pip install sphinx-immaterial[keys]
```

--------------------------------

### Print Hello World in Python

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/content_tabs.rst

A simple Python script demonstrating the 'print' function to output 'Hello world!' to the console. This is a basic example with no external dependencies.

```python
def main():
    print("Hello world!")
```

--------------------------------

### Install sphinx-immaterial with JSON support

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/json/domain.rst

Installs the sphinx-immaterial package with the necessary 'json' extra feature, which includes the PyYAML dependency required for the JSON domain.

```shell
pip install sphinx-immaterial[json]
```

--------------------------------

### Sphinx reST Directive Example

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/rst_basics.rst

Demonstrates the structure of a custom reST directive named 'function'. It shows how to define the directive name, arguments, options, and content. This is a foundational example for understanding custom directive creation in Sphinx.

```rst
.. function:: foo(x)
             foo(y, z)
   :module: some.module.name

   Return a line of text input from the user.
```

--------------------------------

### Implement MyST example directive for Markdown

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/theme_result.rst

Shows the syntax for the myst-example directive, which acts as an alias for rst-example in Markdown files. It supports custom classes, names, and output prefixes for formatted content display.

```md
```{myst-example} A showcase caption
:output-prefix: Which renders the following content:
:class: custom-css-class
:name: reference-this-example

This directive __content__ will be
rendered as a `code snippet` with
**decorated** results.
```
```

--------------------------------

### Python Configuration Example for API Modules

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/apigen.rst

Shows how to configure the `python_apigen_modules` setting in Sphinx's `conf.py` file. This mapping specifies which Python modules to document and their corresponding output path prefixes.

```python
python_apigen_modules = {
    "my_module": "my_api/",
    "my_other_module": "other_api/my_other_module.",
}

```

--------------------------------

### C++ Type Synopsis Example

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

Defines a C++ type 'SomeType' within the 'synopses_ex' namespace, including a tooltip description and additional details. This is used for cross-referencing in documentation.

```cpp
   .. cpp:type:: synopses_ex::SomeType

      Description will be shown as a tooltip when hovering over
      cross-references to :cpp:expr:`SomeType` in other signatures as well as
      in the TOC.

      Additional description not shown in tooltip.  This is the return type
      for :cpp:expr:`Foo`.
```

--------------------------------

### C++ Function Synopsis Example

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

Defines a C++ function template 'Foo' within 'synopses_ex' with type and non-type parameters, and an array parameter. It includes detailed synopses and parameter descriptions for documentation.

```cpp
   .. cpp:function:: template <typename T, int N> \
                     synopses_ex::SomeType synopses_ex::Foo(\
                       T param, \
                       const int (&arr)[N]
                     );

      Synopsis for this function, shown when hovering over cross references
      as well as in the TOC.

      :tparam T: Tooltip shown when hovering over cross-references to this
          template parameter.  Additional description not included in
          tooltip.
      :tparam N: Tooltip shown for N.
      :param param: Tooltip shown for cross-references to this function
          parameter param.
      :param arr: Tooltip shown for cross-references to this function
          parameter arr.  To cross reference another parameter, use the
          :rst:role:`cpp:expr` role, e.g.: :cpp:expr:`N`.  Parameters can
          also be referenced via their fake qualified name,
          e.g. :cpp:expr:`synopses_ex::Foo::N`.
      :returns: Something or other.
```

--------------------------------

### Configure Python API Generation in conf.py

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/apigen.rst

Enables the apigen extension and defines the modules to be documented. This is the primary setup required in the Sphinx configuration file.

```python
extensions = [
    # other extensions...
    "sphinx_immaterial.apidoc.python.apigen",
]

python_apigen_modules = {
      "my_module": "api",
}
```

--------------------------------

### Example of Linked Content Tabs Across Languages

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/content_tabs.rst

Provides an example of using `md-tab-set` and `md-tab-item` directives to create synchronized content tabs. Tabs with identical labels ('Python', 'C++', 'C only') will be selected together when linked via the 'content.tabs.link' feature.

```rst
.. md-tab-set::

    .. md-tab-item:: Python

        .. code-block:: python

            def main():
                print("Hello world!")

    .. md-tab-set::

        .. md-tab-item:: C only

            .. code-block:: c

                #include <stdio.h>

                int main(void) {
                    printf("Hello world!\n");
                    return 0;
                }

        .. md-tab-item:: C++

            .. code-block:: cpp

                #include <iostream>

                int main(void) {
                    std::cout << "Hello world!" << std::endl;
                    return 0;
                }

        .. md-tab-item:: Python

            .. code-block:: python


```

--------------------------------

### Version Dropdown Configuration using JSON File

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/customization.rst

This JSON example demonstrates the content of a `versions.json` file used to configure the version dropdown. It mirrors the structure defined in the `version_info` list, specifying `version`, `title`, and `aliases` for each documentation version.

```json
[
  {"version": "2.0", "title": "2.0", "aliases": ["latest"]},
  {"version": "1.0", "title": "1.0", "aliases": []},
]
```

--------------------------------

### GET /macros/parameters

Source: https://github.com/jbms/sphinx-immaterial/blob/main/tests/snapshots/cpp_domain_test/test_macro_parameter_objects/references.txt

Retrieves the definition and metadata for a specific C macro parameter based on its reference ID.

```APIDOC
## GET /macros/parameters

### Description
Retrieves detailed information about a C macro parameter, including its name and descriptive title.

### Method
GET

### Endpoint
/macros/parameters

### Parameters
#### Query Parameters
- **refid** (string) - Required - The unique reference identifier for the macro parameter (e.g., c.FOO-p-a).

### Request Example
GET /macros/parameters?refid=c.FOO-p-a

### Response
#### Success Response (200)
- **text** (string) - The parameter name.
- **refid** (string) - The unique reference identifier.
- **reftitle** (string) - The full descriptive title of the parameter.

#### Response Example
{
  "text": "a",
  "refid": "c.FOO-p-a",
  "reftitle": "a (C macro parameter) — A parameter."
}
```

--------------------------------

### Python Docstring Example for Class Member Grouping

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/apigen.rst

Demonstrates how to use docstring sections and the `:group:` and `:order:` options to organize class members into logical groups within the generated documentation. This helps in structuring the API reference for classes.

```python
class Foo:
    """This is some class.

    Constructors
    ------------

    This class defines the following constructors.

    Operations
    ----------

    This class supports the following operations.
    """

    def __init__(self):
        """Constructs the class.

        :group: Constructors
        """

    def foo(self):
        """Performs the foo operation.

        :group: Operations
        """

    def bar(self):
        """Performs the bar operation.

        :group: Operations
        """

    def size(self) -> int:
        """Returns the size.

        :group: Accessors
        :order: 2
        """

    def __setitem__(self, i: int, value: int) -> None:
        """Set the element at the given position.

        :group: Indexing
        :order: 3
        """

    def __getitem__(self, i: int) -> int:
        """Returns the element at the given position.

        :group: Indexing
        :order: 1
        """

```

--------------------------------

### Render mathematical equations using LaTeX

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/additional_samples.rst

Utilizes the math directive to render complex mathematical formulas. Supports standard equations and aligned multi-line expressions.

```latex
(a + b)^2 = a^2 + 2ab + b^2

(a - b)^2 = a^2 - 2ab + b^2
```

```latex
\begin{eqnarray}
   y    & = & ax^2 + bx + c \\
   f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}
```

--------------------------------

### Display code blocks with syntax highlighting

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/additional_samples.rst

Demonstrates how to render code blocks using different languages within Sphinx. Supports standard code-block directives for HTML, Python, and JavaScript.

```html
<html>
  <body>Hello World</body>
</html>
```

```python
def hello():
    """Greet."""
    return "Hello World"
```

```javascript
/**
* Greet.
*/
function hello(): {
    return "Hello World";
}
```

--------------------------------

### Document Subscript Syntax

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/index.rst

Provides examples of how subscript syntax is used in Python code, which can be documented using the theme's extended Python domain features.

```python
>>> arr.vindex[1, 2:5, [1, 2, 3]]
ndarray(...)
>>> tensorstore.d[1, "x", 3]
DimSelection(1, "x", 3)
```

--------------------------------

### JSON Structure for Version Information

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/customization.rst

This JSON example illustrates the required structure for version information when using the version dropdown. It includes `version`, `title`, and `aliases` fields, similar to the mkdocs mike plugin.

```json
[
  {"version": "1.0", "title": "1.0", "aliases": []}
  {"version": "2.0", "title": "2.0", "aliases": ["stable"]}
  {"version": "3.0-rc1", "title": "Release Candidate 1", "aliases": ["beta", "latest"]}
]
```

--------------------------------

### Run unit tests with pytest

Source: https://github.com/jbms/sphinx-immaterial/blob/main/tests/README.rst

Executes the project's unit test suite using pytest via the uv package manager. Requires Graphviz to be installed on the host system.

```shell
uv run --group test pytest -vv -s
```

--------------------------------

### Python Type Aliases Configuration Example

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/index.rst

Demonstrates how to configure `python_type_aliases` in Sphinx's conf.py to map unqualified type names to fully qualified ones, and how to map entire modules. This substitution occurs before cross-references are resolved.

```python
# BEGIN: python_type_aliases example
python_type_aliases = {
    "MyUnqualifiedType": "alias_ex.MyUnqualifiedType",
    "example_mod._internal": "example_mod."
}
# END: python_type_aliases example
```

--------------------------------

### Google Analytics Setup and Event Tracking (JavaScript)

Source: https://github.com/jbms/sphinx-immaterial/blob/main/src/templates/partials/integrations/analytics/google.html

This JavaScript code initializes Google Analytics using gtag.js, sends initial page view data, and sets up event listeners for user interactions such as search queries and feedback submissions. It dynamically injects the Google Analytics script into the page.

```javascript
function __md_analytics() {
  window.dataLayer = window.dataLayer || [];
  function gtag() {
    dataLayer.push(arguments);
  }
  /* Set up integration and send page view */
  gtag("js", new Date());
  gtag("config", "{{ property }}");
  /* Register event handlers after documented loaded */
  document.addEventListener("DOMContentLoaded", function() {
    /* Set up search tracking */
    if (document.forms.search) {
      var query = document.forms.search.query;
      query.addEventListener("blur", function() {
        if (this.value) gtag("event", "search", { search_term: this.value });
      });
    }
    /* Set up feedback, i.e. "Was this page helpful?" */
    document$.subscribe(function() {
      var feedback = document.forms.feedback;
      if (typeof feedback === "undefined") return;
      /* Send feedback to Google Analytics */
      for (var button of feedback.querySelectorAll("[type=submit]")) {
        button.addEventListener("click", function(ev) {
          ev.preventDefault();
          /* Retrieve and send data */
          var page = document.location.pathname;
          var data = this.getAttribute("data-md-value");
          gtag("event", "feedback", { page, data });
          /* Disable form and show note, if given */
          feedback.firstElementChild.disabled = true;
          var note = feedback.querySelector(".md-feedback__note[data-md-value='" + data + "']");
          if (note) note.hidden = false;
        });
        /* Show feedback */
        feedback.hidden = false;
      }
    });
    /* Send page view on location change */
    location$.subscribe(function(url) {
      gtag("config", "{{ property }}", { page_path: url.pathname });
    });
  });
  /* Create script tag */
  var script = document.createElement("script");
  script.async = true;
  script.src = "https://www.googletagmanager.com/gtag/js?id={{ property }}";
  /* Inject script tag */
  var container = document.getElementById("__analytics");
  container.insertAdjacentElement("afterEnd", script);
}
```

--------------------------------

### Sphinx reST Substitution Directive

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/rst_basics.rst

Explains reST substitutions, which allow defining reusable pieces of text or markup referenced by `|name|`. It provides examples of defining substitutions using the `replace` directive for text and the `image` directive for images. It also mentions Sphinx's default substitutions and how to manage global substitutions.

```rst
.. |name| replace:: replacement *text*
```

```rst
.. |caution| image:: warning.png
                :alt: Warning!
```

--------------------------------

### Showcase syntax using raw HTML containers

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/theme_result.rst

Demonstrates how to manually wrap content in HTML divs to achieve the theme's showcasing layout when root-level syntax limitations prevent using the built-in directives.

```rst
.. raw:: html

    <div class="results">

.. code-block:: rst

    Some Title
    ==========

    And a page break.

    ----

.. raw:: html

    <div class="result">

Some Title
==========

And a page break.

----

.. raw:: html

    </div></div>
```

--------------------------------

### Enable sphinx-immaterial theme extension

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/theme_result.rst

Configures the Sphinx project to use the theme_result extension required for the showcasing directives.

```python
extensions = [
    "sphinx_immaterial.theme_result",
]
```

--------------------------------

### C++ Constructor with Parameter Descriptions

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

Documents the constructor for 'synopses_ex::Class' in C++, specifying parameters like '_cepin', '_cspin', and '_spi_speed' with their descriptions. Includes a default value for '_spi_speed'.

```cpp
   .. cpp:class:: synopses_ex::Class

       .. cpp:function:: Class(uint16_t _cepin, uint16_t _cspin, uint32_t _spi_speed=RF24_SPI_SPEED)

           :param _cepin: The pin attached to Chip Enable on the RF module
           :param _cspin: The pin attached to Chip Select (often labeled CSN) on the radio module.
           :param _spi_speed: The SPI speed in Hz ie: 1000000 == 1Mhz
```

--------------------------------

### Implement Annotation with Tooltip

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/code_annotations.rst

Example of using the code-annotations directive in reStructuredText to display content within a tooltip. The example demonstrates how the configured width applies to the annotation content.

```yaml
# (1)!

.. code-annotations::
    1. Muuuuuuuuuuuuuuuuuuuuuuuuuuuuch more space!
```

--------------------------------

### Build Documentation for Multiple Versions

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/customization.rst

This command sequence demonstrates how to fetch all tags, checkout specific versions, and build the documentation for each version using sphinx-build. This is a prerequisite for using the version dropdown.

```shell
git fetch --all --tags
git checkout 1.0
sphinx-build docs _build/1.0
git checkout 2.0
sphinx-build docs _build/2.0
```

--------------------------------

### reStructuredText Admonition Directive Examples

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/admonitions.rst

These examples demonstrate various ways to use the generic 'admonition' directive in reStructuredText, including customizing titles, hiding titles, making admonitions collapsible, referencing admonitions by name, and applying custom CSS classes. These showcase the extended functionality provided by the Sphinx Immaterial theme.

```rst
.. tip::
   :title: A custom title specified in the directive's :rst:`:title:` option.

   The :dutree:`tip` directive accepts no arguments.

.. admonition:: A custom title specified in the directive's *argument*.

   Notice the blank line between the directive's beginning block and this content block.

.. legacy:: A custom title specified in both the
   :title: directive's *argument* and :rst:`:title:` option.
      It can even span multiple lines.

   This admonition's directive was created just for this documentation using the
   sphinx-immaterial theme's `Custom Admonitions`_ feature.

.. admonition::

   This *generic* admonition uses the styling of the `note admonition style <note-admonition-style>`.

.. success::
   :no-title:

   This *specific* admonition uses the styling of the `success admonition style`_

.. example:: Opened by default
   :collapsible: open

   Hide me.

.. question:: Closed by default.
   :collapsible:

   Found me.

.. quote:: Referencing an Admonition
   :name: my-admonition

   A reference to :ref:`this admonition <my-admonition>`

.. admonition::
   :class: animated-admonition-border

   .. literalinclude:: _static/extra_css.css
      :language: css
      :caption: docs/_static/extra_css.css
```

--------------------------------

### Python overloaded_func

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

An example of a Python function with multiple signatures using overloaded definitions.

```APIDOC
## Python overloaded_func

### Description
Adds two operands together. Supports integer and float signatures.

### Method
N/A (Python Function)

### Parameters
- **a** (int/float) - Required - First operand.
- **b** (int/float) - Required - Second operand.

### Request Example
overloaded_func(1, 2)

### Response
- **result** (int/float) - The sum of a and b.
```

--------------------------------

### Example: Extracting Value from JSON using C++

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/cpp/external_cpp_references.rst

This reStructuredText example showcases how to use the `cpp:function` role to declare a C++ function signature that references an external type (`::nlohmann::json`). This relies on the `external_cpp_references` extension being configured. The input is the function signature and its description, and the output is a documented C++ function within the Sphinx documentation.

```rst
.. cpp:function:: int ExtractValueFromJson(::nlohmann::json json_value);

    Extracts a value from a JSON object.
```

--------------------------------

### C Macro with Parameter Documentation

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

Defines a C macro 'MY_MACRO' that takes three parameters (X, Y, Z) and includes documentation for each parameter. This aids in understanding macro usage.

```c
   .. c:macro:: MY_MACRO(X, Y, Z)

      Expands to something.

      :param X: The X parameter to the macro.
      :param Y: The Y parameter to the macro.
      :param Z: The Z parameter to the macro.
```

--------------------------------

### POST /zarr/abc/store/Store2

Source: https://github.com/jbms/sphinx-immaterial/blob/main/tests/snapshots/format_signatures_test/test_format_signatures/py_class_constructor_long_astext.txt

Initializes a new instance of the Store2 class with specific mapping requirements and read-only settings.

```APIDOC
## POST /zarr/abc/store/Store2

### Description
Initializes the Store2 object which requires a specific nested mapping structure for data storage configuration.

### Method
POST

### Endpoint
/zarr/abc/store/Store2

### Parameters
#### Request Body
- **some_long_positional_parameter** (MutableMapping) - Required - A mapping where keys are tuples of (str, float, numbers.Real) and values are dictionaries of (int, tuple[list[frozenset[int]]]).
- **read_only** (bool) - Optional - Defaults to False. Determines if the store is restricted to read-only operations.

### Request Example
{
  "some_long_positional_parameter": {
    "('key', 1.0, 10)": { 1: [([1],)] }
  },
  "read_only": false
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of object initialization.

#### Response Example
{
  "status": "success",
  "message": "Store2 instance created"
}
```

--------------------------------

### Sphinx Doctest Blocks

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/rst-cheatsheet/rst-cheatsheet.rst

Explains how to create interactive Python doctest blocks in Sphinx. These blocks start with '>>>' and end with a blank line.

```rst
Doctest blocks are interactive
Python sessions. They begin with
"``>>>``" and end with a blank line.

>>> print "This is a doctest block."
This is a doctest block.
```

--------------------------------

### Using the task-list Directive

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/task_lists.rst

Example of how to use the task-list directive in reStructuredText to create custom-styled, interactive task lists.

```rst
.. task-list::
    :class: custom-task-list-style
    :custom:

    + [ ] Custom unchecked checkbox
    + [x] Custom checked checkbox

      .. task-list::
          :custom:

          * [ ] A goal for a task.
          * [x] A fulfilled goal.
```

--------------------------------

### Configure Sphinx Indexing

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

Shows how to control the generation of indices in Sphinx using configuration variables. Demonstrates the syntax for disabling the HTML index via Python settings.

```python
html_use_index = False
```

--------------------------------

### Configuration Variables

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/apigen.rst

Endpoints and configuration settings for the Sphinx Immaterial extension.

```APIDOC
## GET /confval/python_apigen_rst_prolog

### Description
Defines a string of reStructuredText to be prepended to every docstring. Useful for setting default roles, highlight languages, or literal roles.

### Method
GET

### Endpoint
/confval/python_apigen_rst_prolog

### Parameters
#### Request Body
- **value** (string) - Required - The reStructuredText content to inject.

### Request Example
{
  "python_apigen_rst_prolog": ".. default-role:: py:obj"
}

---

## GET /confval/python_apigen_subscript_method_types

### Description
Configures a regular expression pattern to identify return type annotations for properties that define subscript methods, allowing them to be displayed as subscript syntax (e.g., vindex[sel]).

### Method
GET

### Endpoint
/confval/python_apigen_subscript_method_types

### Parameters
#### Request Body
- **pattern** (string) - Required - Regex pattern matching return type annotations.

### Request Example
{
  "python_apigen_subscript_method_types": "^_Vindex$"
}

---

## GET /confval/python_apigen_show_base_classes

### Description
Boolean flag to toggle the display of base classes when documenting Python classes. Base classes are displayed in standard Python syntax.

### Method
GET

### Endpoint
/confval/python_apigen_show_base_classes

### Parameters
#### Request Body
- **enabled** (boolean) - Required - Whether to show base classes.

### Request Example
{
  "python_apigen_show_base_classes": true
}
```

--------------------------------

### Render Mermaid Class Diagram

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/mermaid_diagrams.rst

Provides an example of modeling object-oriented structures using the classDiagram syntax within the md-mermaid directive.

```rst
.. md-mermaid::
    :name: class-diagrams

    classDiagram
      Person <|-- Student
      Person <|-- Professor
      Person : +String name
      Person : +String phoneNumber
      Person : +String emailAddress
      Person: +purchaseParkingPass()
      Address "1" <-- "0..1" Person:lives at
      class Student{
        +int studentNumber
        +int averageMark
        +isEligibleToEnrol()
        +getSeminarsTaken()
      }
      class Professor{
        +int salary
      }
      class Address{
        +String street
        +String city
        +String state
        +int postalCode
        +String country
        -validate()
        +outputAsLabel()
      }
```

--------------------------------

### Format Scientific Typography and Quotations

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/myst_typography.md

Provides examples for using roles to create subscripts and superscripts, as well as block quotes with attribution attributes.

```markdown
H{sub}`2`O, and 4{sup}`th` of July

{attribution="Hamlet act 4, Scene 5"}
> We know what we are, but know not what we may be.
```

--------------------------------

### Generate Documentation

Source: https://github.com/jbms/sphinx-immaterial/blob/main/CONTRIBUTING.md

Command to build the project documentation using Sphinx via the Nox automation tool. This process sets up a dedicated virtual environment and executes the HTML builder.

```shell
uv run nox -s "docs(html)"
```

--------------------------------

### Module B Submodule Documentation

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

Documentation for module_b.submodule, including nested classes and methods.

```APIDOC
## Module B Submodule Documentation

### Description
Documentation for `module_b.submodule`, including nested classes and methods.

### Classes

#### Class `ModNested`

##### Methods

- **nested_child_1**
  - Description: Links to `nested_child_2`.

- **nested_child_2**
  - Description: Links to `nested_child_1`.

- **getJSON(href, callback, priority[, err_back, flags])**
  - Description: Makes a request to a given URI.
  - Parameters:
    - **href** (string) - Required - An URI to the location of the resource.
    - **callback** - Required - Gets called with the object.
    - **err_back** - Optional - Gets called in case the request fails. And a lot of other text so we need multiple lines.
    - **priority** - Required - Priority of the request.
    - **flags** - Optional - Flags for the request.
  - Throws:
    - SomeError: For whatever reason in that case.
  - Returns:
    - Something.
```

--------------------------------

### Configure Code Block Copy Button

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/customization.rst

Examples of how to enable or disable the code copy button for specific code blocks using the :class: option in reStructuredText.

```yaml
.. code-block:: yaml
    :class: copy

    # Code block content
```

--------------------------------

### Define JavaScript Module and Methods

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

Demonstrates the use of Sphinx JS domain directives to document nested classes and methods. Includes parameter definitions, error handling, and return value descriptions for asynchronous functions.

```rst
.. js:module:: module_b.submodule

.. js:class:: ModNested

   .. js:method:: getJSON(href, callback, priority[, err_back, flags])

      :param string href: An URI to the location of the resource.
      :param callback: Gets called with the object.
      :param err_back: Gets called in case the request fails.
      :throws SomeError: For whatever reason in that case.
      :returns: Something.
```

--------------------------------

### Enable Page Comments

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/customization.rst

Enables comments at the bottom of the current page. Note that enabling comments requires additional setup as detailed in the 'Adding a comment system' instructions.

```rst
:show-comments:
```

--------------------------------

### Configure Prolog and Default Roles in conf.py

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/apigen.rst

Demonstrates how to set the python_apigen_rst_prolog variable to define default roles, literal roles, and highlight languages for generated documentation.

```python
rst_prolog = """
.. role python(code)
   :language: python
   :class: highlight
"""

python_apigen_rst_prolog = """
.. default-role:: py:obj

.. default-literal-role:: python

.. highlight:: python
"""
```

--------------------------------

### Build and Check Tasks

Source: https://github.com/jbms/sphinx-immaterial/blob/main/CONTRIBUTING.md

Commands for building project assets and running quality assurance tools. Includes building CSS/JS bundles and executing type checkers and formatters for both Python and JavaScript/SCSS.

```shell
npm run build
```

```shell
uv run nox
```

```shell
npm run check
```

--------------------------------

### reStructuredText Directive Example: python-apigen-entity-summary

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/apigen.rst

Demonstrates the `python-apigen-entity-summary` directive for generating a summary of a specific Python entity, such as a class member or method. The `entity-name` can include overload information.

```rst
.. python-apigen-entity-summary:: tensorstore_demo.IndexDomain.__init__(json)
   :notoc:

```

--------------------------------

### C++ Foo Function

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/demo_api.rst

A template-based C++ function demonstrating complex parameter handling and documentation.

```APIDOC
## C++ Foo

### Description
Template function that processes an array of data with specified length and optional flags.

### Method
N/A (C++ Function)

### Parameters
- **T** (template) - Required - Some type template parameter.
- **K** (int) - Required - Some non-type template parameter.
- **bar** (MyType) - Required - This is the bar parameter.
- **arr** (uint8_t*/uint16_t*) - Required - Array of something.
- **len** (unsigned int) - Optional - Length of arr (default: DEFAULT_LENGTH).
- **baz** (bool) - Optional - Baz parameter (default: false).

### Response
- **return** (MyType) - The resulting MyType object.
```

--------------------------------

### Create definition lists in reST

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/rst_basics.rst

Illustrates how to define terms and their corresponding indented descriptions, supporting multiple paragraphs.

```rst
term (up to a line of text)
    Definition of the term, which must be indented

    and can even consist of multiple paragraphs

next term
    Description.
```

--------------------------------

### Configure Sphinx theme settings

Source: https://github.com/jbms/sphinx-immaterial/blob/main/README.rst

Required configuration updates for the Sphinx conf.py file to enable the theme and its extension.

```python
extensions = [
    ...,
    "sphinx-immaterial"
]

html_theme = 'sphinx_immaterial'
```

--------------------------------

### Get Value from Storage - JavaScript

Source: https://github.com/jbms/sphinx-immaterial/blob/main/src/templates/partials/javascripts/base.html

Fetches a value associated with a given key from a specified storage (defaults to localStorage). It handles JSON parsing and constructs the storage key using the scope's pathname.

```javascript
const __md_get = (key, storage = localStorage, scope = __md_scope) => ( JSON.parse(storage.getItem(scope.pathname + "." + key)) );
```

--------------------------------

### Doctest Block Example in Python

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/rst_basics.rst

Illustrates the syntax for doctest blocks, which are interactive Python sessions embedded in docstrings. Doctest blocks do not require the literal block syntax and must end with a blank line, but not an unused prompt.

```python
>>> 1 + 1
2
```

--------------------------------

### Integrate clang-format for API signature formatting

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/format_signatures.rst

Shows how to register the signature formatting extension and configure clang-format styles for specific domains within the Sphinx configuration file.

```python
extensions = [
    # other extensions...
    "sphinx_immaterial.apidoc.format_signatures",
]

object_description_options = [
    # ...
    ("cpp:.*", dict(clang_format_style={"BasedOnStyle": "LLVM"})),
]
```

--------------------------------

### Python Module Name Stripping Configuration Example

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/index.rst

Shows how to configure `python_module_names_to_strip_from_xrefs` to remove specific module names from displayed cross-references. This setting only affects the visual representation, not the actual cross-reference target.

```python
# BEGIN: python_module_names_to_strip_from_xrefs example
python_module_names_to_strip_from_xrefs = ["tensorstore_demo"]
# END: python_module_names_to_strip_from_xrefs example
```

--------------------------------

### Subscript Functions and Methods

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/index.rst

Explains the theme's support for documenting subscript functions and methods.

```APIDOC
## Subscript Functions and Methods

**Description**: This theme extends the Python domain to support documenting *subscript methods* (class-scope) and *subscript functions* (module-scope) that enable subscript syntax.

**Example Usage**: 
```python
>>> arr.vindex[1, 2:5, [1, 2, 3]]
ndarray(...)
>>> tensorstore.d[1, "x", 3]
DimSelection(1, "x", 3)
```

**Directive Support**: The theme supports a ``:subscript:`` option for documenting these types of attributes.
```

--------------------------------

### reStructuredText Directive Example: python-apigen-group

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/apidoc/python/apigen.rst

Illustrates the usage of the `python-apigen-group` directive within an reStructuredText file. This directive is used to group module-level members under a specified group name in the generated API documentation.

```rst
.. python-apigen-group:: Some other group
   :notoc:

```

--------------------------------

### C++ Function Signature with Templates and Requires Clause

Source: https://github.com/jbms/sphinx-immaterial/blob/main/tests/snapshots/format_signatures_test/test_format_signatures/cpp_function_long_astext.txt

This C++ function signature showcases template metaprogramming with a requires clause to enforce constraints on template parameters. It includes default values for parameters and a complex return type.

```cpp
template <typename T, typename U = void, int AnotherParameter = 42>
  requires std::is_const_v<T>
const MyType
LongFunctionSignatureExample(const MyType bar, uint8_t *arr,
                             unsigned int len = DEFAULT_LENGTH,
                             bool baz = false);
```

--------------------------------

### Sphinx reST Comment Directive

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/rst_basics.rst

Shows how to create comments in reST. Any explicit markup block that is not a valid directive is treated as a comment. It illustrates single-line comments starting with `..` and multi-line comments formed by indenting text after the `..` marker.

```rst
.. This is a comment.
```

```rst
.. 
    This whole indented block
    is a comment.

    Still in the comment.
```

--------------------------------

### Create definition lists and glossaries

Source: https://github.com/jbms/sphinx-immaterial/blob/main/docs/myst_typography.md

Demonstrates how to define terms and create glossaries using the definition list extension and attributes block. The glossary class allows for cross-referencing terms using the term role.

```markdown
Term 1
: Definition

Term 2
: Longer definition

  With multiple paragraphs

  - And bullet points

{.glossary}
my term
: Definition of the term

{term}`my term`
```