Как правильно начать использовать .readthedocs.yml - PullRequest
Новая
       9

Как правильно начать использовать .readthedocs.yml

1 голос
/ 23 февраля 2020

У меня есть база c Репозиторий ReadTheDocs. Согласно совету на странице сборки, я попытался использовать .readthedocs.yml для его настройки:

Сконфигурировать ваши сборки документации! Добавление файла .readthedocs.yml к вашему Проект - это рекомендуемый способ настройки документации. Вы можете объявить зависимости, настроить подмодули и многое другое.

Я добавил основные c .readthedocs.yml: 

version: 2

sphinx:
  builder: dirhtml
  fail_on_warning: true

и получил ошибку сборки:

Проблема в конфигурации вашего проекта. Неверный "sphinx.builder": .readthedocs.yml: Ваш проект настроен как "Sphinx Html" на панели администратора, но ваш ключ "sphinx.builder" не совпадает.

Это Это было удивительно, так как казалось, что это противоречит указаниям на панели администратора: https://readthedocs.org/dashboard/PROJECTNAME/advanced/, что заставило меня предположить, что я могу установить все, что мне нравится, на панели администратора, но это будет отменено моим .readthedocs.yml (такое поведение я ожидал и хотел):

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

Я обновил настройки на панели администратора, чтобы они соответствовали .readthedocs.yml, а затем получил ошибку сборки: 

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/PROJECT_NAME/checkouts/latest/source/contents.rst not found

что выглядит как https://github.com/readthedocs/readthedocs.org/issues/2569 (RTD не находит конфигурацию Sphinx) - но неясно, почему это происходит, потому что до добавления .readthedocs.yml проект создавался просто отлично.

Я пытаемся смоделировать то, что на самом деле происходит здесь:

  • Файл конфигурации не действует как «оверлей» / «переопределение» для веб-настроек - согласно первой ошибке, некоторые формы несогласия ошибка сборки
  • Это почти , как если бы файл конфигурации существовал, веб-конфигурация игнорировалась - это объясняет возникающую проблему contents.rst, но это не согласуется с первой ошибкой

Добавление записи python.install в .readthedocs.yml в конечном итоге привело к созданию сайта, но мне все еще неясно, правильно ли я поступаю, и / или насколько успешна будущая конфигурация ch будут ангелы.

...