Могу ли я использовать внешние темы с MkDocs на readthedocs.org?

Question

Я переключился с включенной темы «ReadtheDocs» на тему «Объединенная тема» для моего проекта. Я сделал pip install mkdocs-bootswatch по этой теме и изменил theme: readthedocs на theme: united в моем mkdocs.yml файле.

Однако, несмотря на то, что проект успешно завершен в разделе «Чтение документов», документация сохраняет стандартную тему readthedocs. Когда я запускаю его локально (используя mkdocs serve), он выглядит правильно с темой United.

Есть ли еще одна строка кода, которую я должен настраивать где-нибудь? Файл требований, который я должен добавить? Как я могу заставить внешнюю тему правильно отображаться в ReadtheDocs ... или действительно, могу ли я использовать внешние темы для readthedocs.org?

Примечание: Я спросил у людей MkDocs, и они сказали, что это ограничение ReadTheDocs, поэтому, если что-то нужно сделать, похоже, что это будет решение, связанное с ReadTheDocs. В противном случае мне, возможно, придется перейти на страницы GitHub или что-то подобное.

Answer 1

Я взглянул на ReadtheDocs source code и выяснилось, что они фактически переопределяют конфигурацию настроек и создают собственный шаблон. Насколько я понимаю, они делают это, потому что они вводят JavaScript и элементы навигации, специфичные для ReadtheDocs, на ваши страницы и, используя известную тему, они могут быть уверены, что инъекции выполнены правильно. Тем не менее, не должно быть никаких технических причин, по которым вы не можете использовать тот же HTML, что и тема readthedocs, но, возможно, другой CSS, чтобы изменить внешний вид страниц. Это просто, что ReadtheDocs, похоже, явно не поддерживает это.

Это, я заметил, что переопределение шаблона происходит только if 'theme_dir' not in user_config and self.use_theme. Это дает вам два возможных пути, чтобы избежать переопределения. Просто имейте в виду, что не будет никакой гарантии, что впрыскиваемый материал будет работать правильно, поэтому осторожно пройдите.

1. theme_dir является Mkdocs setting. Вместо того, чтобы устанавливать тему MkDocs как отдельную библиотеку Python, вы можете скопировать файлы тем в каталог рядом с docs_dir, а затем указать для него theme_dir. Просто установите theme: null, чтобы MkDocs использовал только theme_dir.

   Возможно, в качестве менее агрессивного подхода вы можете установить theme: readthedocs, а затем использовать theme_dir, чтобы предоставить только собственные CSS-файлы, которые переопределили бы/заменили CSS, предоставленный встроенной темой readthedocs. Это должно быть менее враждебным для инъекций ReadtheDocs и вам понравится. Однако для этого может потребоваться больше работы, так как вы ограничены HTML-темой существующей темы и вам нужно будет создать собственный CSS (без использования уже построенной темы).

   В этом случае вы можете установить theme в любую тему, а затем указать theme_dir в пустой каталог. Казалось бы, ReadtheDocs только проверяет, что установлен theme_dir, и не важно, что на самом деле существует в каталоге.

   Примечание: Я не тестировал ни одно из этих предложений и не могу быть уверенным, что они будут работать. YMMV.

   Как в стороне, документация MkdDocs о том, как все это работает (взаимодействие между настройками theme и theme_dir), сейчас сильно отсутствует. Однако некоторые недавние additions станут живыми, когда выпущена следующая версия MkDocs (0.16).

2. use_theme представляется специфичным для readthedocs и hardcoded внутренне. Я предполагаю, что это не будет чрезмерным для пользователя. Более глубокое исследование кода потребуется для определения того, какие варианты, если таковые имеются, предоставляют.