Недавно мне потребовалось собрать и развернуть документацию для одного из своих небольших проектов на Python. Написал документацию, собрал Sphinx'ом, дальше собрался заливать на readthedocs.org и обнаружил что без VPN сайт не алё. Более того, почему то и с VPN нормально не получалось импортировать свой проект с GitHub.

Не долго думая, решил изучить ситуацию на "рынке" и нашел неплохую альтернативу - GitHub Pages. Эта статья о том, как я деплоил мультиверсионную документацию на GitHub Pages c помощью GitHub Actions (предполагается, что вы хотя бы немного знакомы с данной фичей) и своими собственными "костылями".

Пишем стартовый workflow

Для примера, рассмотрим проект со следующей общей структурой:

.github/
    workflows/
        ...
docs/
    requirements.txt
    source/
        ...
    ...
src/
    ...
LICENSE
README.md
...

В директории docs/source лежат конфигурационные файлы для сборки будущего сайта Sphinx'ом, в docs/requirements.txt соответственно зависимости (sphinx, ...). Вообще говоря, Sphinx в данной статье не по существу, то есть вы можете аналогично использовать другие библиотеки для сборки доков (да и проект может быть вообще не на Python).

Для деплоя документации, главным образом, будем использовать peaceiris/actions-gh-pages. Данный экшон в выбраную ветку (по дефолту это gh-pages) будет заливать собранный сайт с доками. Конечно, можно сливать все в папку docs ветки main, но по-моему отделять документацию от остального проекта куда практичнее.

Напишем теперь наш стартовый workflow для деплоя доков. Создаем файлик docs.yaml в папке .github/workflows:

name: Docs

on:
  push:
    branches: [ main ]
    tags:
      - 'v*.*.*'

permissions:
    contents: write

jobs:
  docs-gen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 1
      - uses: actions/setup-python@v3
        with:
          python-version: 3.7
      - name: Install dependencies
        run: |
          pip install -r docs/requirements.txt
      - name: Sphinx build
        run: |
          sphinx-build docs/source docs/_build
      - name: Deploy docs
        uses: peaceiris/actions-gh-pages@v3
        with:
          allow_empty_commit: true
          personal_token: ${{ secrets.DEPLOY_TOKEN }}
          publish_branch: gh-pages
          publish_dir: docs/_build/

Итак, что здесь происходит? Рассмотрим по шагам. Во-первых, выбираем тригер для запуска нашего workflow:

on:
  push:
    branches: [ main ]
    tags:
      - 'v*.*.*'

Я выбрал вариант c push'ем тага в главную ветку main, что в принципе логично, так деплой документации будет происходить при тагировании новой версии нашего проекта. Как вариант можно сделать это вообще при срезе релиза

on:
  release:
    types: [ created ]

или при самостоятельном запуске в любой момент

on:
  workflow_dispatch:
    inputs:
      ...

В блоке permissions обязательно открываем права на запись. Наконец в нашей джобе docs-gen ставим зависимости из docs/requirements.txt и запускаем sphinx:

- name: Sphinx build
  run: |
    sphinx-build docs/source docs/_build

который собирает доки в папочку docs/_build.

Подключаем экшон actions-gh-pages

- name: Deploy docs
  uses: peaceiris/actions-gh-pages@v3
  with:
    allow_empty_commit: true
    personal_token: ${{ secrets.DEPLOY_TOKEN }}
    publish_branch: gh-pages
    publish_dir: docs/_build/

Данный экшон работает несложно, воспользовавшись стартовым мануалом в большинстве случаев можно достаточно быстро получить желаемый результат. Однако, есть нюанс с которым я столкнулся. Это personal_token. При использовании стандартного GITHUB_TOKEN, то есть

github_token: ${{ secrets.GITHUB_TOKEN }}

смело может вылететь ошибка типа этой:

remote: error: GH006: Protected branch update failed for refs/heads/master.
remote: error: Cannot force-push to this protected branch

В моем случае у меня была установлена защита на ветки, и GITHUB_TOKEN'у не хватало прав для force push'а. Поэтому создаем PAT (Personal Access Token) с нужными правами, добавляем его в секреты (secrets.DEPLOY_TOKEN) репозитория и используем.
В остальном каких-то сильных проблем не было.

Включаем GitHub Pages

Идем в settings нашего репозитория и в разделе Code and automation жмем на Pages. В подразделе Source раздела Build and deployment выбираю Deploy from a branch, а в подразделе Branch выбираю ветку gh-pages и место /root откуда будут грузиться доки. Теперь документация будет грузиться из корня gh-pages.

В принципе на этом и все с настройкой GitHub Pages. Теперь при успешном выполнении нашего workflow Docs, после будет автоматом запущен GitHub Pages'овский workflow pages-build-deployment и станет активным построенный сайт. Перейдя по ссылке типа https://username.github.io/reponame/ сможем увидеть результат.

Добавляем поддержку мультиверсионной документации

Все бы хорошо, но фактически мы сделали только то, что у нас при каждом новом деплое будет перезаписываться все содержимое gh-pages и по итогу на сайте мы будем видеть только документацию для актуальной версии проекта, в то время как для остальных версий все будет стерто. Конечно нас это не устраивает.

Дополним наш workflow.

name: Docs

on:
  push:
    branches: [ main ]
    tags:
      - 'v*.*.*'

permissions:
    contents: write

jobs:
  docs-gen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 1
      - uses: actions/setup-python@v3
        with:
          python-version: 3.7
      - name: Install dependencies
        run: |
          pip install -r docs/requirements.txt
      - name: Sphinx build
        run: |
          sphinx-build docs/source docs/_build
      - name: Deploy docs
        uses: peaceiris/actions-gh-pages@v3
        with:
          allow_empty_commit: true
          destination_dir: ./${{ github.ref_name }}
          force_orphan: false
          keep_files: true
          personal_token: ${{ secrets.DEPLOY_TOKEN }}
          publish_branch: gh-pages
          publish_dir: docs/_build/
      - name: Change redirect
        uses: jannekem/run-python-script-action@v1
        id: script
        with:
          script: |
            import re
            
            path, pattern = "docs/redirect/index.html", re.compile(r"\{\s*%\s*latest-version\s*%\s*}")

            with open(path, "r", encoding="utf8") as file:
                content = pattern.sub("${{ github.ref_name }}", file.read())

            with open(path, "w+", encoding="utf8") as file:
                file.write(content)
      - name: Deploy redirect
        uses: peaceiris/actions-gh-pages@v3
        with:
          allow_empty_commit: true
          force_orphan: false
          keep_files: true
          personal_token: ${{ secrets.DEPLOY_TOKEN }}
          publish_branch: gh-pages
          publish_dir: docs/redirect/

Ставим

destination_dir: ./${{ github.ref_name }}

что бы документация грузилась не в корень ветки gh-pages, а в папку с именем соответствующего тага. В итоге выглядеть это будет как-то так:

v0.1.0/
    ...
v0.2.0/
    ...
...

Используем

keep_files: true

для отмены перезаписи существующих файлов в ветке gh-pages. Однако как указано в документации, actions-gh-pages версия 3 не поддерживает работу с параметром force_orphan, поэтому

force_orphan: false

Итак, теперь для каждого тага будет создаваться документация и помещаться не в корень gh-pages, а в отдельную папку с именем этого тага. Но GitHub Pages грузит сайт с корня ветки. Значит настраиваем редирект. На самом деле здесь можно поступить по-разному. Например, можно в ветке gh-pages дублировать актуальную версию документации в папку с названием main и поместить в корень ветки index.html со следующим содержимым (взято от сюда):

<!DOCTYPE html>
<html>
  <head>
    <title>Redirecting to latest version/</title>
    <meta charset="utf-8">
    <meta content="0; URL=https://username.github.io/reponame/main/index.html" http-equiv="refresh">
    <link href="https://username.github.io/reponame/main/index.html" rel="canonical">
  </head>
</html>

Я же пошел немного другим путем. В папочку docs нашего репозитория добавляем redirect/index.html вида:

<!DOCTYPE html>
<html>
  <head>
    <title>Redirecting to latest-version/</title>
    <meta charset="utf-8">
    <meta content="0; URL=https://username.github.io/reponame/{% latest-version %}/index.html" http-equiv="refresh">
    <link href="https://username.github.io/reponame/{% latest-version %}/index.html" rel="canonical">
  </head>
</html>

а в джобу добавляю 2 шага - Change redirect и Deploy redirect

- name: Change redirect
  uses: jannekem/run-python-script-action@v1
  id: script
  with:
   script: |
     import re
    
     path, pattern = "docs/redirect/index.html", re.compile(r"\{\s*%\s*latest-version\s*%\s*}")

     with open(path, "r", encoding="utf8") as file:
         content = pattern.sub("${{ github.ref_name }}", file.read())

     with open(path, "w+", encoding="utf8") as file:
         file.write(content)
- name: Deploy redirect
  uses: peaceiris/actions-gh-pages@v3
  with:
    allow_empty_commit: true
    force_orphan: false
    keep_files: true
    personal_token: ${{ secrets.DEPLOY_TOKEN }}
    publish_branch: gh-pages
    publish_dir: docs/redirect/

В Change redirect по сути я просто подставляю актуальную версию в заготовленный шаблон, используя для этого регулярку и Python. Понятное дело это можно сделать на любом удобном для вас языке. Наконец в Deploy redirect осуществляю заливку готового редиректа в корень gh-pages. То есть не забываем указать откуда будем деплоить

publish_dir: docs/redirect/

Допиливаем workflow

Представим теперь ситуацию, при которой у нас может быть запущен workflow (например в ручную) для деплоя документации для не самой актуальной версии (возможно нужно, что-то откорректировать в документации к одной из предыдущих версий проекта). Тогда после выполнения, в редиректе изменится версия на не актуальную. Опять дополним наш docs.yaml

name: Docs

on:
  push:
    branches: [ main ]
    tags:
      - 'v*.*.*'

permissions:
    contents: write

jobs:
  docs-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        continue-on-error: true
        with:
          ref: gh-pages
      - name: Check gh-pages versions
        uses: jannekem/run-python-script-action@v1
        id: script
        with:
          script: |
            import pathlib
            import re

            from packaging.version import parse, InvalidVersion
            
            current_version, path = parse("${{ github.ref_name }}"), "./"
            
            with pathlib.Path(path) as dir:
                for file in dir.iterdir():
                    if file.is_dir():
                        try:
                            last_version = parse(file.name)
                            if current_version <= last_version:
                                set_output('is_new_version_docs', 'false')
                                exit()

                        except InvalidVersion:
                            pass
            
            set_output('is_new_version_docs', 'true')
    outputs:
      is_new_version_docs: ${{ steps.script.outputs.is_new_version_docs }}

  docs-gen:
    needs: docs-check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 1
      - uses: actions/setup-python@v3
        with:
          python-version: 3.7
      - name: Install dependencies
        run: |
          pip install -r docs/requirements.txt
      - name: Sphinx build
        run: |
          sphinx-build docs/source docs/_build
      - name: Deploy docs
        uses: peaceiris/actions-gh-pages@v3
        with:
          allow_empty_commit: true
          destination_dir: ./${{ github.ref_name }}
          force_orphan: false
          keep_files: true
          personal_token: ${{ secrets.DEPLOY_TOKEN }}
          publish_branch: gh-pages
          publish_dir: docs/_build/
      - name: Change redirect
        if: needs.docs-check.outputs.is_new_version_docs == 'true'
        uses: jannekem/run-python-script-action@v1
        id: script
        with:
          script: |
            import re
            
            path, pattern = "docs/redirect/index.html", re.compile(r"\{\s*%\s*latest-version\s*%\s*}")

            with open(path, "r", encoding="utf8") as file:
                content = pattern.sub("${{ github.ref_name }}", file.read())

            with open(path, "w+", encoding="utf8") as file:
                file.write(content)
      - name: Deploy redirect
        if: needs.docs-check.outputs.is_new_version_docs == 'true'
        uses: peaceiris/actions-gh-pages@v3
        with:
          allow_empty_commit: true
          force_orphan: false
          keep_files: true
          personal_token: ${{ secrets.DEPLOY_TOKEN }}
          publish_branch: gh-pages
          publish_dir: docs/redirect/

Во-первых, здесь можно увидеть еще одну джобу docs-check в которой и будет лежать проверка на актуальность заливаемой версии. Делаю это как обычно средствами любимого Python'а :) Здесь отмечу данный шаг

- uses: actions/checkout@v3
  continue-on-error: true
  with:
    ref: gh-pages

в котором ставлю continue-on-error: true что бы чекаут не проваливался при первом деплое, когда еще может не быть ветки gh-pages. Также использую ref: gh-pages так как нужна исключительна ветка с доками.

По сути, в данной джобе я просто парсю ветку gh-pages на предмет наличия в ней папки с более актуальной версией. По итогу формирую output is_new_version_docs название которого говорит за себя (в нём будет лежать строкой либо true, либо false).

Наконец в нашу первоначальную джобу docs-gen остается добавить строчку

needs: docs-check

что бы она ожидала выполнения предыдущей джобы, а также добавить условие

if: needs.docs-check.outputs.is_new_version_docs == 'true'

в шаги Change redirect и Deploy redirect.

Переключатель версий

Данный раздел скорее относится к Sphinx, однако я должен упомянуть. На сайте нам желательно иметь красивую "переключалку" между версиями. Изначально я думал для этого использовать sphinx-multiversion, который в нужном стиле при сборке будет добавлять эту самую "переключалку". Однако отказался от этого, так как sphinx-multiversion при построении переключателя версий учитывает только версии которые собирает в данный момент. И проблема именно в том, что пришлось бы всегда все пересобирать с нуля, а пропускать (имитировать) сборку нужной версии он не умеет (проблема обсуждается, например, здесь). То есть если будет огромный проект с кучей документацией для каждой версии, то сборочка мягко говоря немного затянется. Поэтому следуя ответу добавляем файл docs/source/_templates/layout.html

{% extends "!layout.html" %}
{% block menu %}
  <style>
    /* style mobile top nav to look like main nav */
    .wy-nav-top {
        background: {{ theme_style_nav_header_background }}
    }
  </style>
  {{ super() }}
  <!-- Add versions for selected branches + tags -->
  <p class="caption"><span class="caption-text">Versions:</span></p>
  <ul id="versions"/>
  <script>
    // Add any branches to appear in the side pane here, tags will be added below
    // Will only appear if docs are built and pushed in gh-pages
    var versions = ['master', 'main'];
    var dirs = new Set();
    function addVersion(name) {
      if (dirs.has(name)) {
        var li = document.createElement("li");
        var a = document.createElement("a");
        a.href = 'https://username.github.io/{{ project }}/' + name;
        a.innerText = name;
        li.appendChild(a)
        document.getElementById('versions').appendChild(li);
      }
    }
    Promise.all([
      // Find gh-pages directories and populate `dirs`
      fetch("https://api.github.com/repos/username/{{ project }}/contents?ref=gh-pages")
      .then(response => response.json())
      .then(data => data.forEach(function(e) {
        if (e.type == "dir") dirs.add(e.name);
      })),
      // Add tags to `versions`
      fetch('https://api.github.com/repos/reponame/{{ project }}/tags')
        .then(response => response.json())
        .then(data => data.forEach(function(e) {
          versions.push(e.name);
        }))
      ]).then(_ => versions.forEach(addVersion))
  </script>
{% endblock %}

а в конфигурационном файле conf.py Sphinx'а не забываем указать

templates_path = ['_templates']

Заключение

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

Надеюсь было интересно и полезно. Всем спасибо!