Metadata-Version: 2.1
Name: sphinx-material
Version: 0.0.19
Summary: Material sphinx theme
Home-page: https://github.com/bashtage/sphinx-material
Author: Kevin Sheppard
Author-email: kevin.k.sheppard@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Framework :: Sphinx :: Extension
Classifier: Framework :: Sphinx :: Theme
Classifier: Topic :: Documentation :: Sphinx
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.6
Requires-Dist: sphinx (>=2.0)
Requires-Dist: beautifulsoup4
Requires-Dist: python-slugify[unidecode]
Requires-Dist: css-html-js-minify
Requires-Dist: lxml

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 git+https://github.com/bashtage/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

    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:

.. code-block:: python

    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_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.org/bashtage/sphinx-material.svg?branch=master
   :target: https://travis-ci.org/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


