Readthedocs.org: Видение MkDocs в Read the Docs

• Индексирование поиска RTD использовал построитель json (удален в версии 0.17, см. № 4205) для индексации для поиска. Было бы неплохо иметь это или что-то подобное, а не сканировать/индексировать HTML.

MkDocs по-прежнему предоставляет файл JSON, в котором перечислены все страницы с их содержимым, как часть плагина поиска . Очевидно, что RTD не нуждается lunr.js и вспомогательных материалах, но плагин можно настроить так , чтобы он предоставлял только данные JSON. Тем не менее, конфигурация предназначена для определения из конфигурации темы, поэтому, если RTD учитывает выбор темы пользователя, будет сложно переопределить эту конфигурацию. И данные JSON на самом деле разбиты на разделы заголовков, а не полные страницы, которые могут работать или не работать с вашей реализацией поиска.

Тем не менее, не должно быть слишком сложно клонировать соответствующие части плагина для целей RTD. Поскольку плагины могут вставляться в темы, вы даже можете использовать свой плагин для переопределения шаблона versions.html или для добавления собственного JavaScript или любых других модов темы, которые вам могут понадобиться. Другими словами, я считаю, что с помощью одного плагина RTD может легко работать с любой сторонней темой MkDocs, если вы документируете хуки, которые должны предоставить авторы темы. Подробнее см. в документации .

Одна сложная часть — включить ваш плагин в конфигурацию. По умолчанию неопределенная (пользователем) настройка plugins приводит к включению плагина search . Однако, если включены какие-либо пользовательские плагины, то используются только пользовательские плагины (это не аддитивно). Поэтому вам нужно быть осторожным, чтобы не потерять пользовательские плагины при добавлении вашего плагина. За исключением того, что если пользователь явно включил search , вам также потребуется удалить его из списка.

• Стабильность формата Стабильность формата mkdocs.yml, особенно в отношении тем. Здесь было довольно много обратно несовместимых изменений с 0.15.x на 1.x. Поскольку RTD поддерживает несколько версий MkDocs, это было проблемой. Это может стать меньшей проблемой, как только мы перестанем переопределять тему.

Понял. Однако все эти обратно несовместимые изменения были частью разработки до версии 1.0. Теперь, когда выпущена версия 1.0, мы намерены поддерживать стабильность на протяжении всей серии 1.x (версия 2.0 еще не включена в нашу дорожную карту). Будущие изменения должны быть в первую очередь аддитивными и продолжать работать с существующим форматом конфигурации.

Вещи, которые нужны MkDocs от RTD

Помимо перечисленного выше пункта, нам также понадобятся:

• Четкая документация о том, от чего зависит RTD . В идеале должно быть одно место, в котором перечислены все хуки/API, которые использует RTD. Например, если бы такой список существовал, мы могли бы не удалять построитель json , так как у нас сложилось впечатление, что он не используется. Да, эта информация доступна при чтении кода, но это непрактично каждый раз, когда нам нужно быстро проверить. Обратите внимание, что запрошенная документация предназначена не для конечных пользователей, а для разработчиков MkDocs, разработчиков тем и, возможно, разработчиков плагинов. Это может не вписаться в вашу общедоступную документацию, поэтому вики-страница или что-то в этом роде будет в порядке.

Эта проблема была автоматически помечена как устаревшая, поскольку в последнее время с ней не было никаких действий. Он будет закрыт, если никакой дальнейшей активности не произойдет. Спасибо за ваш вклад.

@waylan спасибо, извините за столь поздний ответ. Сейчас мы сосредоточены на улучшении работы MkDocs с RTD, мы собираемся индексировать данные поиска из файла search/search_index.json . Так что было бы хорошо, если бы любое изменение в структуре этого файла было бы удалено или изменено, если есть изменения. Я напишу упомянутый вами документ в ближайшие дни/недели.