SaltStack 项目的 Material Sphinx 主题

这是 Material Sphinx 主题的 SaltStack 主题分支，用于 在 SaltStack 项目中简化使用。

有关使用此主题的已部署文档的示例：

• https://enterprise.saltstack.com

注意：如果想将此用于 个人或非基于 SaltStack Sphinx 的文档项目，您 可能需要使用 Material Sphinx 主题。

注意：对主题所做的任何非 SaltStack 特定的更改， 都应在 Sphinx ( sphinx-material) 项目的上游材料中进行。这些更改可以在下游合并回该项目。

目录

• SaltStack 项目的 Material Sphinx 主题
  • 关于原始材料狮身人面像主题
  • 主题差异
    • 许可差异
  • 安装
  • 配置
  • 自定义布局

关于原始材料狮身人面像主题

Sphinx 文档的 Material Design 主题。基于MkDocs 的材料和Guzzle Sphinx 主题。

• 有关渲染 rst 的示例，请参阅 Sphinx演示站点的原始材料主题。
• 请参阅GitHub 上Sphinx 源代码的原始材料主题。

主题差异

该项目是 Sphinx 项目材料的下游/衍生项目。该项目的主要补充是以下文件：

• 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

主题的其余部分包括对这些新文件的引用。

总体看一下这个存储库中修改过的文件：

• LICENSE.md
  • 请参阅许可差异
• docs/conf.py
  • 由于这是示例演示站点，因此已包含对新主题名称和修改的主题默认值的一些细微更改。
• setup.py
  • 涉及新包/插件命名和其他小杂项的修改。变化。
• sphinx_material/sphinx_material/layout.html
  • 还包括sphinx_material/sphinx_material/static/stylesheets/saltstack.css
• sphinx_material/sphinx_material/theme.conf
  • 修改了特定于 SaltStack 首选项的默认值。

许可差异

由于包含与商标相关的图像，该项目在Apache 2.0许可下发布。具体来说：

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

该项目的其余部分与上游项目相同，后者是在MIT许可下发布的。如果想要衍生这个主题，或者在其他地方包含源代码，最好使用上游主题源：

• 狮身人面像材料（在 GitHub 上）

此存储库的LICENSE文件包括 Apache 2.0 许可证的内容和原始 MIT 许可证的内容。

安装

设置venv：

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

通过 pip 安装：

pip install sphinx-material-saltstack

或者如果您在本地签出代码：

pip install -e .

配置

将以下内容添加到您的导入中conf.py：

import sphinx_material_saltstack

有很多方法可以自定义这个主题，正如这个更全面的示例所示：

# 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,
}

自定义布局

您可以通过覆盖 Jinja 模板块来自定义主题。例如，“layout.html”包含几个可以被覆盖或扩展的块。

layout.html在项目/_templates 目录中放置一个文件。

mkdir source/_templates
touch source/_templates/layout.html

然后，配置您的conf.py：

templates_path = ['_templates']

最后，编辑您的覆盖文件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 %}