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:
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
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.pngsphinx_material_saltstack/sphinx_material_saltstack/static/images/saltstack-logo.pngsphinx_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.mddocs/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
- Made to also include
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.pngsphinx_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:
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 %}
Metadata
Release files for sphinx-material-saltstack 1.0.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sphinx_material_saltstack-1.0.5.tar.gz | 777.6 kB | Without provenance | Details for sphinx_material_saltstack-1.0.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sphinx_material_saltstack-1.0.5-py3-none-any.whl | Python 3 | none | any | Details for sphinx_material_saltstack-1.0.5-py3-none-any.whl |
Total release size: 1.6 MB
Release files / sphinx_material_saltstack-1.0.5.tar.gz
| Download URL | sphinx_material_saltstack-1.0.5.tar.gz |
|---|---|
| Size | 777.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2f2a7cc7c89ff030e1647555e579d654d668cd99a8d854c634f703acbf515909
|
|
BLAKE2b-256 checksum How to use checksums |
881b99ff5958609dfe108c58cd5b8448f63c07031e24c0472a01f2b5e13fb5e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.2
|
Release files / sphinx_material_saltstack-1.0.5-py3-none-any.whl
| Download URL | sphinx_material_saltstack-1.0.5-py3-none-any.whl |
|---|---|
| Size | 802.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4fb05296a82c64488d9616a318f32cd34d26ea2d5c61aa0af7ae8ca529ad0cc4
|
|
BLAKE2b-256 checksum How to use checksums |
dbe2167cd446beeb2cfad42c0f8fe6690c4959d9d11691d2a3548bfa953bf317
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.2
|
Security for sphinx-material-saltstack 1.0.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.