Настройка

Поведение и стиль Alabaster можно настроить несколькими способами:

• Настройки на уровне шаблона или нетривиальные стили могут быть изменены через conf.py в html_theme_options; смотрите Параметры темы.

• Начиная с Alabaster 0.7.8, вы можете переопределить стили CSS через пользовательские таблицы стилей. Этот вариант подходит для таких изменений, которые требуют незначительных модификаций CSS.

  Примечание

  Некоторые варианты темы, реализованные до 0.7.8, лучше было бы реализовать с помощью переопределений в пользовательских таблицах стилей. Поэтому:

  • Мы больше не принимаем запросы на новую функциональность, которую вместо этого лучше реализовать вышеупомянутым способом.

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

  Если сомневаетесь, просто проверьте шаблон встроенной таблицы стилей, чтобы увидеть, можно ли получить нужный вам вариант, вставив значение одной из базовых переменных, или нужно что-то более сложное.

Пользовательские таблицы стилей

Если вам нужно изменить стили CSS в Alabaster таким способом, который не описан в следующем разделе, вы можете предоставить собственную таблицу стилей CSS следующим образом:

• Создайте файл с именем custom.css где угодно (обычно в папке static/, но необязательно, это не более чем соглашение), содержащий желаемые переопределения CSS, имеющихся в static/alabaster_css_t.

• Укажите в параметре Sphinx html_static_path либо путь к вашему файлу, либо к каталогу, в котором он находится.

(Примечание переводчика: начиная с версии Sphinx 1.8 можно использовать параметр html_css_files.)

Параметры темы

Основной путь конфигурации Alabaster — это внесение изменений в переменную html_theme_options, находящуюся в conf.py, например:

html_theme_options = {
    'logo': 'logo.png',
    'github_user': 'bitprophet',
    'github_repo': 'alabaster',
}

В следующих подразделах подробно описаны такие параметры, с примечаниями о результирующем поведении. Значения по умолчанию можно найти непосредственно в theme.conf.

Основные параметры

Параметры отображения текста, логотипа и так далее.

• body_text_align: Какое значение CSS text-align использовать для основного текста (если используется).

• canonical_url: Если указано, используется в качестве базового URL (устанавливается перед относительным путем / именем_страницы) для тега <link rel="canonical"> канонического URL.

  Примечание

  Это значение должно заканчиваться косой чертой.

• description: Описание вашего провекта в двух словах, отображается под логотипом.

• description_font_style: Какой font-style использовать для текста в description.

• fixed_sidebar: Делает боковую панель «фиксированной», закрепленной на месте таким образом, чтобы основная часть страницы прокручивалась, а боковая панель оставалась видимой. (Применяется только в окнах достаточно больших размеров; при уменьшении размеров окна или просмотре страниц на мобильных устройствах не действует.)

• logo: Относительный путь (от $ PROJECT/_static/) к изображению с логотипом, который отображается в левом верхнем углу над названием проекта.

  Если значение для logo не указано, на месте логотипа будет отображаться название проекта, указанное в project (одна из основных настроек Sphinx) в виде текстового заголовка. По ссылке в этом заголовке можно перейти на домашнюю страницу с внутренних страниц документа.

• logo_name: Укажите true, чтобы название вашего проекта из project отображалось под логотипом. Полезно в тех случаях, когда на логотипе нет названия проекта.

• logo_text_align: Какое значение text-align использовать для текста под логотипом (если используется).

• page_width: Спецификатор CSS, управляющий шириной содержимого страницы.

• sidebar_width: Спецификатор CSS, управляющий шириной боковой панели.

• touch_icon: Путь к изображению (как и в случае с logo, относительно $PROJECT/_static/), которое используеться для иконки приложения iOS при сохранении страницы на домашнем экране устройства iOS через Safari.

Ссылки и значки сервисов

Сторонние сервисы (GitHub, Travis-CI и прочие) и соответствующие значки или баннеры.

• analytics_id: Укажите свой ID в Google Analytics (например, UA-#######-##), чтобы включить отслеживание.

• badge_branch: Укажите, какая ветка используется для значков Travis, CodeCov и т. д.

• codecov_button: true, false или строка в стиле Github "account/repo" — используется для отображения кнопки статуса сборки Codecov на боковой панели. Если указано true, используются ваши настройки github_(user|repo).

• donate_url: URL для общего / произвольного сервиса пожертвования; вызывает отображение базового значка «Donate» (с https://shields.io) со ссылкой на указанный URL.

• github_banner: true или false — нужно ли отображать баннер «Fork me on Github» в верхнем правом углу страницы.

  • Для true нужно указать также github_user и github_repo (см. ниже).

  • Также можно указать строку с путем к файлу изображения (как и с logo, относительно $PROJECT/_static/), которое будет использовано в качестве баннера вместо изображения по умолчанию

• github_button: true или false — отображать ли ссылку на ваш Github.

  • Для true нужно указать также github_user и github_repo.

  • Есть также параметры github_type и github_count, которые действуют в соответствии с описанием в документации к Github Buttons.

• github_repo: Этот параметр используют github_button и github_banner (см. выше); ничего не делает, если оба из них установлены в false.

• github_user: Этот параметр используют github_button и github_banner (см. выше); ничего не делает, если оба из них установлены в false.

• gittip_user / gratipay_user: Устарело, так как этот сервис больше не работает. Эти параметры все еще существуют (если их удалить, может пострадать обратная совместимость; Sphinx сообщает об ошибке, когда пользователи пытаются установить несуществующие параметры), но они больше ничего не делают.

• tidelift_url: Укажите URL вашего проекта Tidelift, если вам нужен раздел «Профессиональная поддержка» на боковой панели.

  Если вы копируете URL прямо с сайта Tidelift, вы, вероятно, захотите заменить &utm_campaign=readme на &utm_campaign=docs.

• travis_button: true, false или строка в стиле Github "account/repo" — используется для отображения статуса сборки Travis-CI на боковой панели. Если указано true, используются ваши настройки github_(user|repo).

Прочие элементы боковой панели

Параметры боковой панели, которые не имеют прямого отношения к ссылкам на сервисы.

• extra_nav_links: Словарь вида «имя ссылки: адрес»; эти ссылки отображаются ниже основной боковой панели навигации (если navigation.html включен в html_sidebars; см. Установка). Полезно для статических ссылок на страницы, не входящие в ваш проект Sphinx.

• show_related: Отображать ли на боковой панели навигационные ссылки «next/previous/related» (true или false). По умолчанию используется значение false, поскольку на многих сайтах эти элементы излишни.

  Примечание

  Это не то же самое, что show_relbars в параметрах верхнего и нижнего колонтитулов; эти два визуальных компонента ортогональны и могут быть включены и выключены независимо друг от друга.

• sidebar_collapse: Должны ли быть свернуты элементы оглавления, которые идут после текущего элемента (true или false). См. подробнее в документации Sphinx.

• sidebar_includehidden: Нужно ли отображать на боковой панели скрытые элементы оглавления. По умолчанию true, так что вы можете использовать :hidden: в корневом узле toctree (в файле index.rst или его эквиваленте) и избежать дублирования навигации на главной странице.

Верхний и нижний колонтитулы

Параметры отображения элементов в верхнем и нижнем колонтитулах.

• show_powered_by: Отображать ли блок Powered by Sphinx NNN & Alabaster MMM в нижнем колонтитуле. Если указано true, блок отображается рядом с информацией об авторских правах; если false, блок скрыт.

• show_relbars: true или false — используется для отображения ссылок next и previous над и под содержимым главной страницы. Если вы хотите, чтобы ссылки отображались только вверху или только внизу, переопределите этот параметр через show_relbar_top и show_relbar_bottom.

  Примечание

  Это не то же самое, что show_related в настройках боковой панели; последние контролируют отображение ссылок «next/previous» только на боковой панели.

Цвета

Для указания цвета нужно использовать полные цветовые спецификаторы CSS вроде #004B6B или #444. Первые несколько элементов в списке — «глобальные» цвета, которые используются по умолчанию для многих других; измените их, чтобы значительно поменять цветовую схему При необходимости можно переопределить более детальные настройки.

• anchor: Цвет якорных ссылок на разделы (символ ¶, который появляется при наведении мыши на заголовки разделов).

• anchor_hover_bg: Цвет фона для якорной ссылки при наведении мыши на якорную ссылку.

• anchor_hover_fg: Цвет текста для якорной ссылки при наведении мыши на якорную ссылку.

• body_text: Цвет текста страницы.

• code_highlight: Цвет подсветки при использовании :emphasize-lines: в блоке кода.

• footer_text: Цвет текста нижнего колонтитула (включая ссылки).

• footnote_bg: Фон блоков сносок.

• footnote_border: Цвет границы в блоках сносок.

• gray_1: Темно-серый.

• gray_2: Светло-серый.

• gray_3: Серый.

• link_hover: Цвет ссылки при наведении мыши.

• link: Цвет ссылки без наведения мыши.

• narrow_sidebar_bg: Фон боковой панели, когда из-за уменьшения ширины окна боковая панель оказывается в нижней части страницы.

• narrow_sidebar_fg: Цвет текста боковой панели в вышеописанном случае.

• narrow_sidebar_link: Цвет ссылок на боковой панели в вышеописанном случае.

• note_bg: Фон блоков .. note:: («Примечание»).

• note_border: Цвет границы в блоках .. note::.

• pink_1: Светло-розовый.

• pink_2: Розовый.

• pre_bg: Фон блоков предварительно отформатированного текста (включая фрагменты кода).

• relbar_border: Цвет границы между полосой со ссылками next и previous и остальной частью страницы.

• seealso_bg: Фон блоков .. seealso:: («См. также»).

• seealso_border: Цвет границы в блоках .. seealso::.

• sidebar_header: Заголовки боковой панели.

• sidebar_hr: Цвет боковых горизонтальных разделителей.

• sidebar_link: Цвет ссылок на боковой панели (варианта с наведением мыши нет). Относится и к заголовокам, и к ссылкам в тексте.

• sidebar_list: Цвет текста маркированных списков и текста без ссылок на боковой панели.

• sidebar_link_underscore: Подчеркивание ссылок на боковой панели (технически это нижняя граница).

• sidebar_search_button: Цвет фона на кнопке «Искать».

• sidebar_text: Текст абзацев на боковой панели.

• warn_bg: Фон блоков .. warning:: («Предупреждение»).

• warn_border: Цвет границы в блоках .. warning::.

Шрифты

• caption_font_size: Размер шрифта в блоке заголовка.

• caption_font_family: Семейство шрифтов в блоке заголовка.

• code_font_size: Размер шрифта в блоке кода.

• code_font_family: Семейство шрифтов в блоке кода. Значения по умолчанию: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace.

• font_family: Семейство шрифтов основного текста.

• font_size: Размер шрифта основного текста.

• head_font_family: Семейство шрифтов в заголовках. По умолчанию используется 'Garamond', 'Georgia', serif.