Три способа публикации документации Sphinx

Интеграция с GitHub Actions и автоматическая публикация

В предыдущей статье мы обсуждали, как быстро генерировать документацию с помощью инструментов Sphinx CLI. В этой статье я продемонстрирую три различных способа публикации документации Sphinx. Следовательно, любой, у кого есть URL-адрес, может просматривать вашу документацию.

Я также интегрирую процессы публикации в GitHub Actions, чтобы они были полностью автоматизированы.

Опубликовать на страницах GitHub

GitHub Pages — хороший инструмент для размещения статического веб-сайта, например документации Sphinx. Я использую это действие GitHub, actions-gh-pages, для развертывания моей документации на страницах GitHub.

Его очень просто использовать. Вам просто нужно указать путь к вашей документации, например. docs/build, то это действие поможет вам справиться с остальными шагами!

- name: Publish to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: docs/build

Когда все будет готово, вы сможете просмотреть опубликованную документацию из https://<username>.github.io/<repository_name>/.

Довольно легко, правда? Переходим к следующей платформе.

Публикация в облачном хранилище GCP

Я рекомендую использовать действие GitHub upload-cloud-storage для загрузки вашей документации в GCS. Есть три шага, чтобы использовать это действие. Во-первых, настройте разрешение для своего задания, чтобы у вызывающей стороны было разрешение на доступ к секретам GitHub. Поскольку я также использую git-auto-commit-action для фиксации изменений, contents также следует установить как write.

permissions:
  contents: ‘write’
  id-token: ‘write’

Во-вторых, аутентифицируйте действие с помощью google-github-actions/auth, чтобы мы могли загружать файлы в GCS. Наконец, укажите каталог вашей документации и целевую корзину, например. my-sample-bucket-123.

- name: Gcloud Auth
  uses: ‘google-github-actions/auth@v0’
  with:
    credentials_json: ${{ secrets.GCP_CREDENTIALS }}
- name: Upload documentation to GCS
  uses: ‘google-github-actions/upload-cloud-storage@v0’
  with:
    path: ‘docs/build’
    destination: ‘my-sample-bucket-123’

Следующим шагом нам нужно сделать все объекты под my-sample-bucket-123 общедоступными. Следовательно, люди могут читать документацию в Интернете. Шаги можно найти здесь. Теперь вы можете просматривать свою документацию через https://storage.googleapis.com/<bucket-name>/build/index.html.

Однако GCS не поддерживает пользовательские домены. Вы можете настроить Балансировщик нагрузки перед GCS. Но это выходит за рамки данной статьи, поэтому я не буду обсуждать это здесь.

Вот полный рабочий процесс. Всякий раз, когда создается документация, этот рабочий процесс автоматически публикует нашу документацию на страницах GitHub и GCS.

Опубликовать в ReadTheDocs

В отличие от двух других способов, после того, как вы выполните инструкции по импорту проекта в readthedocs, он автоматически создаст документацию и инициирует сборку всякий раз, когда вы меняете репозиторий.

После того, как вы импортируете проект, вам нужно перейти в Admin › Advanced Settings, под Default settings указать путь к файлу требований и путь к conf.py, чтобы он мог правильно построить документацию.

Когда вы видите Passed на вкладке Builds, это означает, что документация успешно создана! Нажмите View Docs, чтобы просмотреть документацию. Общедоступный URL-адрес будет https://<project-name>.readthedocs.io.

Краткое содержание

В последней статье мы создали скрипт для создания красивой документации и интеграции ее с GitHub Actions. В этой статье мы продемонстрировали три способа автоматической публикации вашей документации. Таким образом, теперь у нас есть полный конвейер для создания и размещения нашей документации! Я надеюсь, что вы найдете эти две статьи полезными для создания конвейера документации.

Полные примеры вы можете найти в этом репозитории.