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

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

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

11
css python-sphinx read-the-docs restructuredtext

1 ответов

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

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

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

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

Прецедент: Hatnotes

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

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

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

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

вот мой пользовательский CSS для hatnotes. Я сохранил это в _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 в макет. Использование шаблонов хорошо документировано at sphinxdoc.org. В шаблоне переопределения просто установите css-files переменная (массив) с добавленным списком Ваших пользовательских файлов CSS.

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

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

это все, что вам нужно сделать для темы по умолчанию. Для темы Сфинкс / RTD есть дополнительный шаг, где вы...

Шаг 3: Добавьте Таблицы Стилей в тему

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

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

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

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

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

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

вот как создать 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, который вы помещаете под

19