Как настроить пользовательские стили для reStructuredText, Sphinx, ReadTheDocs и т.д.?

Ответ 1

Предположения

Ваш набор документов RTD имеет что-то вроде следующей структуры:

• (корневой путь)
  • (некоторые другие вещи, не связанные с этим обсуждением)
  • _static/
  • _templates/
  • conf.py

Вы также создаете локально, используя sphinx-build или sphinx-autobuild, используя тему по умолчанию, но вместо этого ваш развернутый сервер может использовать sphinx-rtd-theme.

Пример использования: Hatnotes

Для этой иллюстрации я собираюсь показать, как создать пользовательский стиль для "шляпников" - концепции, которая распространена в документах MediaWiki и которая примерно соответствует конструкции admonition в RST. Вы можете применить то, что показано здесь, для создания любого настраиваемого CSS и включить его в свой набор документов.

Шаг 1. Создание пользовательского CSS

Пользовательский файл CSS должен находиться где-то в каталоге _static/, так как там, где процесс сборки и скрипты найдут его. Я бы рекомендовал подкаталог css/, так как вы могли бы добавить другие настройки, например файлы JavaScript.

Создайте свой собственный CSS файл и поместите его в этот каталог. Напишите свои спецификации стиля в качестве наложения к тому, что уже существует в теме, которую вы будете использовать в сборке. Также не предполагайте, будет ли ваш стиль переопределять существующий стиль в теме, поскольку вы не можете гарантировать, когда ваши стили будут добавлены по отношению к стандартным.

Здесь мой пользовательский CSS для шляп. Я сохранил это при _static/css/hatnotes.css.

.hatnote
{
    border-color: #c8c8c8 ;
    border-style: solid ;
    border-width: 1px ;
    font-size: x-small ;
    font-style: italic ;
    margin-left: auto ;
    margin-right: auto ;
    padding: 3px 2em ;
}
.hatnote-gray { background-color: #e8e8e8 ; color: #000000 ; }
.hatnote-yellow { background-color: #ffffe8 ; color: #000000 ; }
.hatnote-red { background-color: #ffe8e8 ; color: #000000 ; }
.hatnote-icon { height: 16px ; width: 16px ; }

Шаг 2: добавление стилей в шаблоны

Для темы по умолчанию достаточно создать шаблон, который переопределяет значение по умолчанию layout.html, чтобы добавить свой собственный CSS в макет. Использование шаблонов хорошо документировано на sphinxdoc.org. В шаблоне переопределения просто установите переменную css-files (массив) с добавленным списком ваших пользовательских файлов CSS.

Вот мой шаблон, который добавляет Hatnotes CSS. Я сохранил это как _templates/layout.html.

{% extends "!layout.html" %}
{% set css_files = css_files + [ "_static/css/hatnotes.css" ] %}

Это все, что вам нужно сделать для темы по умолчанию. Для темы Sphinx/RTD есть еще один шаг, где вы & hellip;

Шаг 3: добавление стилей в тему

Для темы Sphinx/RTD ваш шаблон будет проигнорирован. Вместо использования механизма шаблона вам нужно добавить функцию в ваш файл conf.py, который добавит файл CSS в тему приложения. Где-то рядом, где ваш файл conf устанавливает атрибут html_theme, добавьте что-то вроде следующего:

def setup(app):
  app.add_stylesheet( "css/hatnotes.css" )

Обратите внимание, что на этот раз там нет _static/ в начале пути; функция add_stylesheet() предполагает, что часть пути.

Завершение использования случая

Теперь, когда вы настроили свои собственные стили как для темы по умолчанию, так и для темы Sphinx/RTD, вы можете фактически использовать их в своем документе.

Следуя обычной парадигме определения штемпелей в качестве "шаблонов" в MediaWiki (извините, не так же, как шаблоны в Sphinx и RTD), я создал каталог includes/, где будут храниться все мои шляпки.

Здесь как построить шляпу с информацией пользовательского стиля. Этот файл includes/hatnotes/stub-article.rst.

.. container:: hatnote hatnote-gray

   |stub| This article is a stub. Please improve the docs by expanding it.

.. |stub| image:: /images/icons/stub.png
          :class: hatnote-icon

Здесь мы создаем шляпу "заглушки", чтобы иметь стиль по умолчанию для шляпок, серый фон и использовать значок "заглушка" в качестве встроенного изображения с стилем hatnote-icon, применяемым к этому изображению.

Теперь мы можем использовать файл в качестве включенного ресурса в документе.

Foo Article
===========

.. include:: /includes/hatnotes/stub-article.rst

Blah blah I haven't written this article yet.

Если вы используете локальную тему по умолчанию или тему Sphinx/RTD, то шляпка будет отображаться с добавленными вами стилями, настроив шаблон _templates/layout.html и conf.py script, чтобы включить в него пользовательский CSS файл, который вы помещаете в каталог _static/.

Конечное состояние

В вашем хранилище документов теперь есть этот материал:

• (корневой путь)
  • _static/
    • css/
      • (пользовательские файлы CSS и hellip;)
  • _templates/
    • layout.html — (добавляет ваш пользовательский CSS в макет по умолчанию)
  • conf.py — (с новой функцией для добавления пользовательского CSS в тему приложения)