Блог

В качестве учебного упражнения я хотел бы развить тему 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
.venvscriptsactivate
python -m pip install sphinx
sphinx-quickstart site #I opted for different source and build folders
cd site
mkdir _themes
xcopy ...venvLibsite-packagesalabaster _themesalabaster2 /E
 

Я обновил раздел вывода HTML в sourceconf.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
 

Сгенерированный buildhtmlindex.html файл работает не так, как ожидалось, например, ни один из параметров, заданных в словаре html_theme_options , расположенном в conf.py , не принимается во внимание.

Версии программного обеспечения

 (.venv) >python --version
Python 3.8.8

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

После прочтения документации (!) Я пришел к выводу, что я делаю это неправильно, т. Е. «чтобы использовать тему Spinx по умолчанию», вам не нужно редактировать шаблоны Jinja!

Например, предположим, что вы хотите добавить следующие функции в тему алебастра Сфинкса по умолчанию:

• CSS для выравнивания изображений по центру
• javascript для получения согласия на использование файлов cookie
• Импорт CSS начальной загрузки
• Включите изображение логотипа

В этом посте я отвечу и прокомментирую свой собственный вопрос, а также покажу, как результат, показанный ниже, может быть довольно легко достигнут при минимальном кодировании.

Установка по умолчанию в Windows 10

 python -m venv .venv
.venvscriptsactivate
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;
  }
 

2. Добавьте изображение логотипа в source/_static/img/logo.png

3. Добавьте source_templateslayout.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-attributionamp;amp;utm_medium=referralamp;amp;utm_campaign=imageamp;amp;utm_content=5719221>`_ from `Pixabay <https://pixabay.com/?utm_source=link-attributionamp;amp;utm_medium=referralamp;amp;utm_campaign=imageamp;amp;utm_content=5719221>`_.


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



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

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

Изображение, используемое в примере

Изображение Томислава Якупека из Pixabay

Сделать html

В терминале выполните make html и откройте файл build/html/index.html