Material Sphinx Theme
=====================
**Continuous Integration**
|Travis Build Status|
**Release**
|PyPI Status|
**License**
|MIT License|
A Material Design theme for Sphinx documentation. Based on
`Material for MkDocs <https://squidfunk.github.io/mkdocs-material/>`_,
and `Guzzle Sphinx Theme <https://github.com/guzzle/guzzle_sphinx_theme>`_.
See the theme's `demonstration site <https://bashtage.github.io/sphinx-material/>`_
for examples of rendered rst.
Installation
------------
Install via pip:
.. code-block:: bash
$ pip install sphinx-material
or if you have the code checked out locally:
.. code-block:: bash
$ python setup.py install
Configuration
-------------
Add the following to your conf.py:
.. code-block:: python
html_theme = 'sphinx_material'
There are a lot more ways to customize this theme, as this more comprehensive
example shows:
.. code-block:: python
# 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,
}
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.
.. code-block:: bash
mkdir source/_templates
touch source/_templates/layout.html
Then, configure your 'conf.py':
.. code-block:: python
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 %}
.. |Travis Build Status| image:: https://travis-ci.com/bashtage/sphinx-material.svg?branch=master
:target: https://travis-ci.com/bashtage/sphinx-material
.. |PyPI Status| image:: https://badge.fury.io/py/sphinx-material.svg
:target: https://badge.fury.io/py/sphinx-material
.. |MIT License| image:: https://img.shields.io/badge/License-MIT-blue.svg
:target: https://opensource.org/licenses/MIT-Clause
Raw data
{
"_id": null,
"home_page": "https://github.com/bashtage/sphinx-material",
"name": "sphinx-material",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Kevin Sheppard",
"author_email": "kevin.k.sheppard@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/53/e9/5473d3bfc7516d97eb73bb0bce51c964b2aa4d29f84509c097229343275c/sphinx_material-0.0.36.tar.gz",
"platform": null,
"description": "Material Sphinx Theme\r\n=====================\r\n\r\n**Continuous Integration**\r\n\r\n|Travis Build Status|\r\n\r\n**Release**\r\n\r\n|PyPI Status|\r\n\r\n**License**\r\n\r\n|MIT License|\r\n\r\nA Material Design theme for Sphinx documentation. Based on\r\n`Material for MkDocs <https://squidfunk.github.io/mkdocs-material/>`_,\r\nand `Guzzle Sphinx Theme <https://github.com/guzzle/guzzle_sphinx_theme>`_.\r\n\r\nSee the theme's `demonstration site <https://bashtage.github.io/sphinx-material/>`_\r\nfor examples of rendered rst.\r\n\r\nInstallation\r\n------------\r\n\r\nInstall via pip:\r\n\r\n.. code-block:: bash\r\n\r\n $ pip install sphinx-material\r\n\r\nor if you have the code checked out locally:\r\n\r\n.. code-block:: bash\r\n\r\n $ python setup.py install\r\n\r\nConfiguration\r\n-------------\r\n\r\nAdd the following to your conf.py:\r\n\r\n.. code-block:: python\r\n\r\n html_theme = 'sphinx_material'\r\n\r\n\r\nThere are a lot more ways to customize this theme, as this more comprehensive\r\nexample shows:\r\n\r\n.. code-block:: python\r\n\r\n # Required theme setup\r\n html_theme = 'sphinx_material'\r\n\r\n # Set link name generated in the top bar.\r\n html_title = 'Project Title'\r\n\r\n # Material theme options (see theme.conf for more information)\r\n html_theme_options = {\r\n\r\n # Set the name of the project to appear in the navigation.\r\n 'nav_title': 'Project Name',\r\n\r\n # Set you GA account ID to enable tracking\r\n 'google_analytics_account': 'UA-XXXXX',\r\n\r\n # Specify a base_url used to generate sitemap.xml. If not\r\n # specified, then no sitemap will be built.\r\n 'base_url': 'https://project.github.io/project',\r\n\r\n # Set the color and the accent color\r\n 'color_primary': 'blue',\r\n 'color_accent': 'light-blue',\r\n\r\n # Set the repo location to get a badge with stats\r\n 'repo_url': 'https://github.com/project/project/',\r\n 'repo_name': 'Project',\r\n\r\n # Visible levels of the global TOC; -1 means unlimited\r\n 'globaltoc_depth': 3,\r\n # If False, expand all TOC entries\r\n 'globaltoc_collapse': False,\r\n # If True, show hidden TOC entries\r\n 'globaltoc_includehidden': False,\r\n }\r\n\r\nCustomizing the layout\r\n----------------------\r\n\r\nYou can customize the theme by overriding Jinja template blocks. For example,\r\n'layout.html' contains several blocks that can be overridden or extended.\r\n\r\nPlace a 'layout.html' file in your project's '/_templates' directory.\r\n\r\n.. code-block:: bash\r\n\r\n mkdir source/_templates\r\n touch source/_templates/layout.html\r\n\r\nThen, configure your 'conf.py':\r\n\r\n.. code-block:: python\r\n\r\n templates_path = ['_templates']\r\n\r\nFinally, edit your override file 'source/_templates/layout.html':\r\n\r\n::\r\n\r\n {# Import the theme's layout. #}\r\n {% extends '!layout.html' %}\r\n\r\n {%- block extrahead %}\r\n {# Add custom things to the head HTML tag #}\r\n {# Call the parent block #}\r\n {{ super() }}\r\n {%- endblock %}\r\n\r\n.. |Travis Build Status| image:: https://travis-ci.com/bashtage/sphinx-material.svg?branch=master\r\n :target: https://travis-ci.com/bashtage/sphinx-material\r\n\r\n.. |PyPI Status| image:: https://badge.fury.io/py/sphinx-material.svg\r\n :target: https://badge.fury.io/py/sphinx-material\r\n\r\n.. |MIT License| image:: https://img.shields.io/badge/License-MIT-blue.svg\r\n :target: https://opensource.org/licenses/MIT-Clause\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Material sphinx theme",
"version": "0.0.36",
"project_urls": {
"Homepage": "https://github.com/bashtage/sphinx-material"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0aaa8173e966607bc9db8c40fd18382e8b0d4f19be002bc1449c160c0e93814c",
"md5": "6aa6c4fc31b02a593579a08ce48787c6",
"sha256": "1d7f972cca7ebdfe135e28f18401673306d7c0d036d42c6e3d98b77394e61a60"
},
"downloads": -1,
"filename": "sphinx_material-0.0.36-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6aa6c4fc31b02a593579a08ce48787c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 790400,
"upload_time": "2023-08-18T12:23:35",
"upload_time_iso_8601": "2023-08-18T12:23:35.409412Z",
"url": "https://files.pythonhosted.org/packages/0a/aa/8173e966607bc9db8c40fd18382e8b0d4f19be002bc1449c160c0e93814c/sphinx_material-0.0.36-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "53e95473d3bfc7516d97eb73bb0bce51c964b2aa4d29f84509c097229343275c",
"md5": "84516fcb4d63920dc88418d25d9afccd",
"sha256": "eeff5f7d3dc016af32bafdf70c66e671d15c8754dbe0613dfbd629fbed912869"
},
"downloads": -1,
"filename": "sphinx_material-0.0.36.tar.gz",
"has_sig": false,
"md5_digest": "84516fcb4d63920dc88418d25d9afccd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 783660,
"upload_time": "2023-08-18T12:23:45",
"upload_time_iso_8601": "2023-08-18T12:23:45.419232Z",
"url": "https://files.pythonhosted.org/packages/53/e9/5473d3bfc7516d97eb73bb0bce51c964b2aa4d29f84509c097229343275c/sphinx_material-0.0.36.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-18 12:23:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bashtage",
"github_project": "sphinx-material",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sphinx-material"
}
JSON
