Adaptation of mkdocs-material theme for the Sphinx documentation system
Project description
This theme is an adaptation of the popular mkdocs-material theme for the Sphinx documentation tool.
This theme is regularly maintained to stay up to date with the upstream mkdocs-material repository. The HTML templates, JavaScript, and styles from the mkdocs-material theme are incoroprated directly with mostly minor modifications.
This theme is a fork of the sphinx-material theme, which proved the concept of a Sphinx theme based on an earlier version of the mkdocs-material theme, but has now significantly diverged from the upstream mkdocs-material repository.
See the TensorStore documentation for a demonstration of this theme.
WARNING: This theme is currently still a work in progress. The documentation is largely copied from sphinx-material and is inaccurate for this version. It does not yet integrate well with numpydoc or the built-in autosummary.
Installation
Install via pip:
$ pip install sphinx-immaterialor if you have the code checked out locally:
$ pip -install -e .Configuration
In your conf.py add sphinx_immaterial as an extension:
extensions = [
...,
"sphinx_immaterial"
]and add the following:
html_theme = 'sphinx_immaterial'to set the theme.
Customizing the layout
You can customize the theme by overriding Jinja template blocks. For example, ‘layout.html’ contains several blocks that can be overridden or extended.
Place a ‘layout.html’ file in your project’s ‘/_templates’ directory.
mkdir source/_templates
touch source/_templates/layout.htmlThen, configure your ‘conf.py’:
templates_path = ['_templates']Finally, edit your override file ‘source/_templates/layout.html’:
{# Import the theme's layout. #}
{% extends '!layout.html' %}
{%- block extrahead %}
{# Add custom things to the head HTML tag #}
{# Call the parent block #}
{{ super() }}
{%- endblock %}
Differences from mkdocs-material
This theme closely follows the upstream mkdocs-material repository, but there are a few differences, primarily due to differences between Sphinx and MkDocs:
This theme adds styles for Sphinx object descriptions, commonly used for API documentation (e.g. class and function documentation). This is a core element of Sphinx for which there is no corresponding feature in MkDocs.
mkdocs-material uses lunr.js for searching, and has custom UI components for displaying search results in a drop-down menu as you type the search query. This theme uses a separate search implementation based on the custom index format used by Sphinx, which fully integrates with the search UI provided by mkdocs-material.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
File details
Details for the file sphinx_immaterial-0.4.1-py3-none-any.whl.
File metadata
- Download URL: sphinx_immaterial-0.4.1-py3-none-any.whl
- Upload date:
- Size: 4.8 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.0 CPython/3.8.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 833051e5e0921b09e232ba8cc4aff701e7dfc5a9db74e88402ae585fbc14c940 |
|
| MD5 | 2d63271bd833dcd7296d0846088e5296 |
|
| BLAKE2b-256 | f9463331c5cceb74f6b21b4b532c0d9293350a02f3634223a3f7973f434fba5a |
