Material sphinx theme
Project description
Continuous Integration
Release
License
A Material Design theme for Sphinx documentation. Based on Material for MkDocs, and Guzzle Sphinx Theme.
See the theme’s demonstration site for examples of rendered rst.
Installation
Install via pip:
$ pip install git+https://github.com/bashtage/sphinx-material
or if you have the code checked out locally:
$ python setup.py install
Configuration
Add the following to your conf.py:
import sphinx_material
# Register the theme as an extension to generate a sitemap.xml
extensions.append('sphinx_material')
# Choose the material theme
html_theme = 'sphinx_material'
# Get the them path
html_theme_path = sphinx_material.html_theme_path()
# Register the required helpers for the html context
html_context = sphinx_material.get_html_context()
There are a lot more ways to customize this theme, as this more comprehensive example shows:
import sphinx_material
# Required theme setup
extensions.append('sphinx_material')
html_theme = 'sphinx_material'
html_theme_path = sphinx_material.html_theme_path()
html_context = sphinx_material.get_html_context()
# Material theme options (see theme.conf for more information)
html_theme_options = {
# Set the name of the project to appear in the navigation.
'nav_name': 'Project Name',
# Set you GA account ID to enable tracking
'google_analytics_account': 'UA-XXXXX',
# Specify a base_url used to generate sitemap.xml. If not
# specified, then no sitemap will be built.
'base_url': 'https://project.github.io/project',
# Set the color and the accent color
'color_primary': 'blue',
'color_accent': 'light-blue'
# Set the repo location to get a badge with stats
'repo_url': 'https://github.com/project/project/',
'repo_name': 'Project',
# Visible levels of the global TOC; -1 means unlimited
'globaltoc_depth': 3,
# If False, expand all TOC entries
'globaltoc_collapse': False,
# If True, show hidden TOC entries
'globaltoc_includehidden': False,
}
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.html
Then, 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 %}
Project details
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
Hashes for sphinx_material-0.0.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 55c05c481da0823b289c5d3b1e088f5f64b5c15404f64853b2e1ae2051f55974 |
|
MD5 | ee81244e5ee3774e1fff6b3abdaaf501 |
|
BLAKE2b-256 | f4d6f776974c0fb160701c71bcecae07c97b44d1f03de08f58a4290a1bbb0c7c |