时间戳

首页 > 解决方案 > 编辑 Sphinx Alabaster jinja 模板

python-sphinx - 编辑 Sphinx Alabaster jinja 模板

问题描述

作为一项教育练习，我想在默认 Spinx 主题 Alabaster 的基础上进行构建，并通过在 jinja 模板中进行更改来添加其他功能。

因此，我设置了一个虚拟环境，安装了 Sphinx，将 Alabaster 文件夹复制到我的工作文件夹_themes/Alabaster2，更新conf.py并编译了一个 HTML 项目。这种方法导致了几个缺失的依赖项。比如连要继承的“基本”主题都找不到！文件中的所有html_theme_options设置都conf.py不起作用。

如何克服这些缺点，即在我的工作文件夹中有 Alabaster 的工作副本并对 jinja 模板进行更改？

如果任何有为 Sphinx 文档系统开发主题的经验的人可以阐明如何设置一个可以调整 Alabaster 使用的模板的环境，那将不胜感激！

关于我的（失败的）方法的其他详细信息

在 Windows 10 上工作，通过在终端中执行以下命令来设置项目

python -m venv .venv
.venv\scripts\activate
python -m pip install sphinx
sphinx-quickstart site #I opted for different source and build folders
cd site
mkdir _themes
xcopy ..\.venv\Lib\site-packages\alabaster _themes\alabaster2\ /E

我更新了 HTML 输出部分source\conf.py

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#

html_theme_path = ["_themes"]

html_theme = 'alabaster2'

html_theme_options = {
    'logo': 'logo.png',
    'description':'Welcome to MySite',
    'description_font_style':'Monospace',
    'fixed_sidebar':True,
    'logo_name':False,
    'logo_text_align':None,
    'page_width':'90%',
    'sidebar_width':'280px',
    # 'analytics_id':'UA-#######-##', 
    #'donate_url':'www.paypal.com',
    # 'extra_nav_links':True,
    'show_related':False,
    'show_relbars':True,
    'sidebar_collapse':True,
    'show_powered_by':True,
}

然后在终端

make html

生成的build\html\index.html文件没有按预期工作，例如，没有考虑html_theme_options位于的字典中设置的任何选项。conf.py

软件版本

(.venv) >python --version
Python 3.8.8

(.venv) >sphinx-build --version
sphinx-build 4.2.0

标签： python-sphinx

解决方案

阅读文档（！）后，我得出结论，我的做法是错误的，即“以默认 Spinx 主题 Alabaster 为基础”，您无需编辑 Jinja 模板！

例如，假设您想将以下功能添加到默认的 Sphinx Alabaster 主题中：

  • CSS居中对齐图像
  • 用于 cookie 同意的 javascript
  • 导入引导 CSS
  • 包含徽标图片

在这篇文章中，我将回答并评论我自己的问题，并展示如何以最少的代码轻松实现下面的结果。

在 Sphinx 中调整雪花石膏主题的最终结果

Windows 10 上的默认安装

python -m venv .venv
.venv\scripts\activate
python -m pip install sphinx
sphinx-quickstart site #I opted for different source and build folders
cd site

更新source/conf.py

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

html_title = 'SOLUTION'

# Custom css files
html_css_files = [
    'css/custom.css',
]

html_theme_options ={
    'logo':'img/logo.png',
    'description':'Washing machines works better with software',
    'description_font_style':'Monospace',
    'fixed_sidebar':True,
    'logo_name':False,
    'logo_text_align':None,
    'page_width':'75%',
    'sidebar_width':'250px',
    # 'analytics_id':'UA-#######-##', 
    #'donate_url':'www.paypal.com',
    # 'extra_nav_links':True,
    'show_related':False,
    'show_relbars':True,
    'sidebar_collapse':True,
    'show_powered_by':True,
}

添加自定义css和html

  1. 添加source/_static/css/custom.css托管.centeralign类。
.centeralign {
    display: block;
    margin-left: auto;
    margin-right: auto;
    width: 50%;
    margin-top: 40px;
    margin-bottom: 30px;
  }
  1. 将徽标图像添加到source/_static/img/logo.png

虚构的标志灰尘

  1. 添加source\_templates\layout.html下面列出的内容
{% extends "!layout.html" %}

{% block extrahead %}
  {{ super() }}
    <!-- Code for cookie consent -->
    <script></script>
{% endblock %}

{% block linktags %}
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
{% endblock %}

source/index.rst

将以下代码添加到index.rst

.. DUST documentation master file, created by
   sphinx-quickstart on Tue Oct 26 08:47:02 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to DUSTS's documentation!
=================================

Insert an image and style with Bootstrap classes.

.. code-block:: reStructuredText

   .. image:: _static/img/abstract-g90ed47336_1280.jpg
      :alt: DUST washing cloud
      :class: img-fluid, rounded, mx-auto, d-block, shadow-sm, my-3

.. image:: _static/img/abstract-g90ed47336_1280.jpg
  :alt: DUST washing cloud
  :class: img-fluid, rounded, mx-auto, d-block, shadow-sm, my-3


Image by `Tomislav Jakupec <https://pixabay.com/users/tommyvideo-3092371/?utm_source=link-attribution&amp;utm_medium=referral&amp;utm_campaign=image&amp;utm_content=5719221>`_ from `Pixabay <https://pixabay.com/?utm_source=link-attribution&amp;utm_medium=referral&amp;utm_campaign=image&amp;utm_content=5719221>`_.


.. toctree::
   :maxdepth: 2
   :caption: Contents:



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

示例中使用的图像

图片来自 Pixabay.com

该图片由Tomislav Jakupec在Pixabay上发布

制作html

在终端执行make html并打开文件build/html/index.html

推荐阅读