Material Sphinx Theme for SaltStack Projects

This is a SaltStack-themed fork of the Material Sphinx Theme for simplified use in SaltStack projects.

For an example of deployed documentation using this theme:

• https://enterprise.saltstack.com

NOTE: If wanting to use this for personal or non-SaltStack Sphinx-based documentation projects, you may want to use the Material Sphinx Theme instead.

NOTE: Any changes to the theme, that are non-SaltStack specific, should be done to the upstream Material for Sphinx (sphinx-material) project. Those changes can be merged downstream back to this project.

Table of Contents

• Material Sphinx Theme for SaltStack Projects
  • About the Original Material Sphinx Theme
  • Theme Differences
    • License Differences
  • Installation
  • Configuration
  • Customizing the layout

About the Original Material Sphinx Theme

A Material Design theme for Sphinx documentation. Based on Material for MkDocs, and Guzzle Sphinx Theme.

• See the original Material Theme for Sphinx demonstration site for examples of rendered rst.
• See the the original Material Theme for Sphinx source code on GitHub.

Theme Differences

This project is a downstream/derivative of the Material for Sphinx project. The primary additions to this project are the following files:

• sphinx_material_saltstack/sphinx_material_saltstack/static/images/favicon.png
• sphinx_material_saltstack/sphinx_material_saltstack/static/images/saltstack-logo.png
• sphinx_material_saltstack/sphinx_material_saltstack/static/stylesheets/saltstack.css

The rest of the theme includes references to these new files.

Overall look at modified files in this repository:

• LICENSE.md
  • See License Differences
• docs/conf.py
  • Since this is the example demo site, some minor changes of the new theme name and modified theme defaults, have been included.
• setup.py
  • Modifications referring to new package/plugin naming, and other small misc. changes.
• sphinx_material/sphinx_material/layout.html
  • Made to also include sphinx_material/sphinx_material/static/stylesheets/saltstack.css
• sphinx_material/sphinx_material/theme.conf
  • Modified defaults that are specific to SaltStack preferences.

License Differences

This project is released under the Apache 2.0 license, due to the inclusion of trademark-related images. Specifically:

• sphinx_material/sphinx_material/static/images/favicon-salt.png
• sphinx_material/sphinx_material/static/images/saltstack-logo.png

The rest of the project is otherwise the same as the upstream project, which is released under the MIT license. If wanting to make a derivative of this theme, or include the source code elsewhere, it would be a better idea to make use of the upstream theme source:

• sphinx-material (on GitHub)

The LICENSE file of this repository includes both the content of the Apache 2.0 license, and the content of the original MIT license.

Installation

Setup venv:

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip setuptools wheel

Install via pip:

pip install sphinx-material-saltstack

or if you have the code checked out locally:

pip install -e .

Configuration

Add the following to your imports in conf.py:

import sphinx_material_saltstack

There are a lot more ways to customize this theme, as this more comprehensive example shows:

# Required theme setup
html_theme = 'sphinx_material_saltstack'

# 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.gitlab.io/project',

    # Set the repo location to get a badge with stats
    'repo_url': 'https://gitlab.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 %}