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.
Install via pip:
$ pip install sphinx-materialor if you have the code checked out locally:
$ python setup.py installAdd the following to your conf.py:
html_theme = 'sphinx_material'There are a lot more ways to customize this theme, as this more comprehensive example shows:
# Required theme setup html_theme = 'sphinx_material' # Set link name generated in the top bar. html_title = 'Project Title' # Material theme options (see theme.conf for more information) html_theme_options = { # Set the name of the project to appear in the navigation. 'nav_title': '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, }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 %}