#gitlab #python-sphinx #read-the-docs #gitlab-ce
# #gitlab #python-sphinx #читайте-the-docs #gitlab-ce
Вопрос:
Предыстория
Я технический писатель, пытающийся использовать Read the Docs для создания документации для одного из наших продуктов. Поскольку у нас есть соглашение о неразглашении для любой публикации, я должен разместить документацию на виртуальной машине для клиентов с доступом к интрасети для чтения.
Установка
GitLab
Моя виртуальная машина — CentOS 8. Я установил GitLab Community Edition через Docker. Я создал репозиторий для своего исходного кода Markdown под учетной записью root с адресом репозитория http://${vm_address}/root/${repo_name} . Контейнер GitLab запускается на порту 20 моей виртуальной машины.
Прочитайте документы
Поскольку RTD официально не поддерживает локальное развертывание, я извлек неофициальный образ из Docker. См. vassilvk / readthedocs . Этот контейнер RTD работает на порту 8000 моей виртуальной машины. Я использую имя пользователя «admin» для входа в RTD.
Процедура, которую я предпринял для интеграции GitLab и RTD
Чтобы импортировать исходный код в мою GitLab, я сделал следующее:
- На странице проекта нажмите Импортировать проект.
- Нажмите Импортировать вручную на левой панели.
- На странице сведений о проекте заполните поля следующим образом:
- Имя проекта: $ {my_project_name}
- URL репозитория: $ {Clone_With_HTTP_Address}
I copied the URL from the "Clone with HTTP" field under the Clone button dropdown in GitLab - Тип репозитория: Git
- В дополнительных параметрах проекта я установил тип документации на Sphinx HTML.
- Нажмите Готово.
Результат
Сбой сборки с кодом ошибки 1 .
Вопрос
- Где я ошибся с настройками проекта RTD?
- Что-то не так происходит с моими настройками контейнера RTD или GitLab?
- Нужно ли мне все еще устанавливать Sphinx на виртуальную машину?
Комментарии:
1. Я думаю, что вы делаете это излишне сложным. Добавьте в свой CI GitLab перехват, который создает документы с использованием Sphinx и развертывает их там, где вы хотите, без RTD.
2. Спасибо, Стив. Я собираюсь обсудить с разработчиком возможность использования GitLab CI для создания и страницы GitLab для размещения моего документа.
Ответ №1:
Поскольку у нас есть соглашение о неразглашении для любой публикации, я должен разместить документацию
Из этого вообще ничего не следует. вы, должно быть, смотрите не на те ReadTheDocs. Есть два сайта:
- ReadTheDocs.org — это бесплатный, общедоступный хостинг.
- ReadTheDocs.com — это то, что вам нужно, в нем размещены частные репозитории для компаний, точно таких же, как ваша.
Если вы не работаете в хорошо управляемой и безопасной ИТ-среде, запуск случайных образов Docker на вашей собственной виртуальной машине почти наверняка приведет к непреднамеренному раскрытию информации. Вы занимаетесь хостинговым бизнесом? Нет. Не занимайтесь хостингом, когда все, чего вы хотите, — это написать какую-то частную документацию. Для этого есть продукты.
Комментарии:
1. Спасибо за комментарий! Образ RTD в Docker, который я установил на своей виртуальной машине, на самом деле является копией бесплатной версии RTD, потому что моя компания только начинает и, по-видимому, не хочет тратить бюджет на Doc на ранней стадии. Я удалил это случайное изображение со своей виртуальной машины и рассматриваю возможность использования страницы GitLab для размещения моего HTML, созданного автоматическим заданием Дженкинса.