Alabaster: тема для Sphinx

Что такое Alabaster?

Alabaster — это легкая, адаптивная, настраиваемая тема для генератора документации Sphinx. Она совместима с Python версий 2 и 3.

Проект начинался как отдельный от Sphinx, и все еще поддерживается отдельно, но на момент выхода версии Sphinx 1.3 Alabaster указан как зависимость во время установки Sphinx и выбран в качестве темы по умолчанию.

Живые примеры использования Alabaster можно увидеть на собственном веб-сайте проекта, на paramiko.org, fabfile.org и pyinvoke.org.

Оригинал документации на английском языке смотрите на http://alabaster.readthedocs.io.

Примечание

Вы можете установить версию для разработки через pip install -e git+https://github.com/bitprophet/alabaster/#egg=alabaster.

Особенности

  • Возможность легко установить и использовать как пакет Python (мое почтение создателям sphinx_rtd_theme Дейву и Эрику за то, что показали, как это делается).

  • Лучшая подгонка стилей по сравнению с исходными темами, как то: лучшее выравнивание блоков кода, расположение кнопок Github, перенос ссылки на источник страницы в нижний колонтитул, улучшенная боковая панель со связанными элементами, и многое другое.

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

  • Улучшена документация для всех параметров (ранее существовавших и новых).

Обзорная информация о проекте

Alabaster — это модифицированная версия темы для Sphinx «krTheme» от Кеннета Райца (эта тема используется в его проекте Requests). В свою очередь, тема Кеннета изначально была основана на теме Армина Ронахера для Flask. Большое спасибо обоим за их усердную работу.

Примечания к реализации

  • На Fabric #419 много моих общих соображений и мыслей, возникавших во время разработки Alabaster, в частности, в связи с намерением использовать его на двух почти идентичных связанных сайтах (информационный сайт с единственной версий и сайт с документацией к API разных версий).

  • Alabaster предполагает установку маленького расширения Sphinx поверх самой темы; это только для того, чтобы можно было вводить динамические метаданные (например, номера версий Alabaster) в контекст шаблона. Это не добавляет никаких дополнительных директив или чего-то еще, по крайней мере, пока.