SaltStack项目的Material Sphinx主题

这是一个为简化SaltStack项目使用而修改的 Material Sphinx Theme 的SaltStack主题。

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

• https://enterprise.saltstack.com

**注意**：如果想要在 个人或非SaltStack Sphinx-based文档项目中使用此主题，您可能希望使用Material Sphinx Theme。

**注意**：对主题的任何非SaltStack特定的更改应应用到Material for Sphinx (sphinx-material) 项目。这些更改可以合并到下游项目中。

目录

• SaltStack项目的Material Sphinx主题
  • 关于原始Material Sphinx主题
  • 主题差异
    • 许可证差异
  • 安装
  • 配置
  • 自定义布局

关于原始Material Sphinx主题

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

• 请参阅Sphinx原版Material主题的演示网站，以查看rst渲染的示例。
• 请参阅Sphinx原版Material主题的GitHub源代码。

主题差异

此项目是Material for 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许可下发布。如果想要创建此主题的衍生品或在其他地方包含源代码，最好使用上游主题源

• sphinx-material (在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'包含几个可以覆盖或扩展的块。

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

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 %}