Развертывание документации MkDocs в Read Docs с использованием личного репозитория организации

Question

В настоящее время я ухожу со стажировки, и сейчас я пишу документацию для летнего стажера, который вступит в должность после окончания школы.Я написал все свои документы в Markdown, используя MkDocs, и я готов развернуть их.Мои документы используют тему «Читать документы», которая поставляется вместе с MkDocs, и я надеялся разместить их на RTD.Тем не менее, код для моих документов размещен в частном репозитории, принадлежащем организации GitHub моей компании.У меня проблемы с настройкой RTD, поскольку я лично не владею репо.У кого-нибудь из вас есть такой опыт?Я посмотрел на MkDocs «Развертывание ваших документов» , но все гиперссылки устарели, и руководство в основном охватывает ссылки на публичные репозитории.

Также - я незамужем за RTD, это просто тема MkDocs, которую я использовал в своих документах, так что, если у кого-то из вас есть другие предложения, отойдите!

Answer 1

RTD, похоже, переместил свою документацию в https://docs.readthedocs.io/en/latest/. Документация RTD, относящаяся к MkDocs, находится по адресу https://docs.readthedocs.io/en/latest/intro/getting-started-with-mkdocs.html,, однако в ней нет никаких инструкций по развертыванию сайта на основе MkDocs.

Как это происходит, процесс развертывания в RTD одинаков независимо от того, какой из поддерживаемых генераторов статического сайта вы используете (Sphinx или MkDocs) и задокументирован в https://docs.readthedocs.io/en/latest/intro/import-guide.html:

ToИмпортируйте общедоступный репозиторий документации, перейдите на страницу . Прочитайте панель инструментов Docs и нажмите Импорт.Для частных репозиториев используйте коммерческое решение Read the Docs .

Если у вас подключена ваша учетная запись Read Docs к GitHub, Bitbucket или GitLab, вы увидитесписок ваших репозиториев, которые мы можем импортировать .Чтобы импортировать один из этих проектов, просто щелкните значок импорта рядом с хранилищем, которое вы хотите импортировать.Откроется форма, которая уже заполнена информацией о вашем проекте.Не стесняйтесь редактировать любое из этих свойств, а затем нажмите Далее до Создайте свою документацию .

Обратите внимание, что если у вас нет (или вы хотитеиметь) вашу учетную запись GitHub, связанную с вашей учетной записью RTD, тогда вам нужно будет вручную импортировать репо, что задокументировано здесь .Документация продолжается:

В течение нескольких секунд после завершения процесса импорта ваш код будет автоматически получен из вашего общедоступного хранилища, и документация будет собрана.Посетите нашу страницу Процесс сборки , чтобы узнать больше о том, как Read Docs создает ваши документы, и устранить любые возникающие проблемы.

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

В последний раз, когда я проверял, RTD не использовал самый последний выпуск MkDocs по умолчанию, поэтому вы можете использоватьreadthedocs.yml файл для указания версии MkDocs, для которой вы написали свои документы, а также любых сторонних плагинов, тем и / или расширений Markdown, которые вы используете.