:hero: A responsive Material Design theme for Sphinx sites.

===================
Material for Sphinx
===================

..
    .. image:: images/screenshot.png
        :alt: Material for Sphinx Screenshots

This theme is an adaptation of the popular `mkdocs-material
<https://github.com/squidfunk/mkdocs-material/>`__ theme for the `Sphinx
<https://www.sphinx-doc.org/>`__ documentation tool.

This theme is regularly maintained to stay up to date with the upstream
`mkdocs-material <https://squidfunk.github.io/mkdocs-material/>`__ repository.
The HTML templates, JavaScript, and styles from the `mkdocs-material
<https://squidfunk.github.io/mkdocs-material/>`__ theme are incoroprated directly
with mostly minor modifications.

Independent of the upstream mkdocs-material theme, this theme integrates with
and significantly extends Sphinx's API documentation functionality.

This theme is a fork of the `sphinx-material
<https://github.com/bashtage/sphinx-material>`__ theme, which proved the concept
of a Sphinx theme based on an earlier version of the `mkdocs-material
<https://squidfunk.github.io/mkdocs-material/>`__ theme, but has now
significantly diverged from the upstream `mkdocs-material
<https://squidfunk.github.io/mkdocs-material/>`__ repository.

Getting Started
---------------

.. admonition:: Prerequisites

    Building the theme from source requires node.js v14 or newer installed.
    Please be aware that readthedocs.org uses a docker image that might have
    an outdated verson of node.js installed. Installing node.js from a Unix package
    manager may not provide version 14 or newer.

    Installing from a distributed wheel (such as from pypi.org) does not require
    node.js installed.

Install from git source

.. code-block:: bash

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

Update your ``conf.py`` with the required changes:

.. code-block:: python

    extension = ["sphinx_immaterial"]
    # ...
    html_theme = "sphinx_immaterial"


There are a lot more ways to customize this theme. See :ref:`Customization`
or ``theme.conf`` for more details.

.. details:: Settings used in this documentation
    :class: example

    .. literalinclude:: ./conf.py
        :start-after: # -- HTML theme specific settings
        :end-before: # end html_theme_options


.. toctree::
    :hidden:

    customization
    admonitions
    content_tabs
    task_lists
    keys
    code_syntax_highlighting

.. toctree::
    :caption: API documentation customization
    :hidden:

    apidoc/index
    apidoc/format_signatures
    apidoc/python/index
    apidoc/python/apigen
    apidoc/cpp/index
    apidoc/cpp/external_cpp_references
    apidoc/cpp/cppreference
    apidoc/cpp/apigen
    apidoc/json/domain

.. toctree::
    :caption: Diagrams/graphs
    :hidden:

    graphviz
    mermaid_diagrams

.. toctree::
    :caption: Examples and Uses
    :hidden:

    demo_api
    python_apigen_demo
    cpp_apigen_demo
    specimen
    rst_basics
    rst-cheatsheet/rst-cheatsheet
    additional_samples
