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

Я хочу расширить тему, используемые сфинкс и ReadTheDocs с моей собственные стили.

Как лучше всего это сделать, чтобы мои изменения остались?

1 11
css restructuredtext python-sphinx

1 ответ:

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

Ваш набор RTD doc имеет примерно следующую структуру:

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

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

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

Для этого иллюстрация, я собираюсь показать, как создать пользовательский стиль для "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 есть дополнительный шаг, где вы... Шаг 3: Добавление таблиц стилей в тему

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

def setup(app):
  app.add_stylesheet( "css/hatnotes.css" )
Обратите внимание, что на этот раз нет _static/ в передней части пути; функция add_stylesheet() принимает эту часть пути.

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

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

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

Вот как построить hatnote с пользовательской информацией о стиле. Этот файл называется 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, чтобы иметь стиль hatnote по умолчанию, серый фон, и используем значок "заглушки" в качестве встроенного изображения, с hatnote-icon стилем, применяемым к этому изображению.

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

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

Blah blah I haven't written this article yet.

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

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

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

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