如何使用 GitHub 页面自行托管阅读文档

Question

如何设置 CI/CD workflow with gitlab (or GitHub Actions) that generates my own Read the Docs site and is hosted for free using gitlab pages？

gitlab 或 github 上是否有可用于自行生成和自行托管我自己的阅读文档站点的 fork-ready 示例存储库？

Answer 1

您可以在 GitHub 页面上托管一个由 sphinx 驱动的网站（可选择使用阅读文档主题），使用 GitHub 操作来包装 sphinx-build 并推送您的 html 静态资产到您的 GitHub 页面源，例如 gh-pages branch..

您需要定义一个GitHub Actions workflow来执行构建脚本。

这是一个示例工作流程，每次推送到 master

时都会执行 buildDocs.sh

name: docs_pages_workflow
 
# execute this workflow automatically when a we push to master
on:
  push:
    branches: [ master ]
 
jobs:
 
  build_docs_job:
    runs-on: ubuntu-latest
    container: debian:buster-slim
 
    steps:
 
    - name: Prereqs
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        apt-get update
        apt-get install -y git
        git clone --depth 1 "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" .
      shell: bash
 
    - name: Execute script to build our documentation and update pages
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: "docs/buildDocs.sh"
      shell: bash

下面是一个示例 buildDocs.sh 由上面的工作流执行的脚本：

#!/bin/bash
################################################################################
# File:    buildDocs.sh
# Purpose: Script that builds our documentation using sphinx and updates GitHub
#          Pages. This script is executed by:
#            .github/workflows/docs_pages_workflow.yml
#
# Authors: Michael Altfield <michael@michaelaltfield.net>
# Created: 2020-07-17
# Updated: 2020-07-17
# Version: 0.1
################################################################################
 
###################
# INSTALL DEPENDS #
###################
 
apt-get update
apt-get -y install git rsync python3-sphinx python3-sphinx-rtd-theme
 
#####################
# DECLARE VARIABLES #
#####################
 
pwd
ls -lah
export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
 
##############
# BUILD DOCS #
##############
 
# build our documentation with sphinx (see docs/conf.py)
# * https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build
make -C docs clean
make -C docs html
 
#######################
# Update GitHub Pages #
#######################
 
git config --global user.name "${GITHUB_ACTOR}"
git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
 
docroot=`mktemp -d`
rsync -av "docs/_build/html/" "${docroot}/"
 
pushd "${docroot}"
 
# don't bother maintaining history; just generate fresh
git init
git remote add deploy "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
git checkout -b gh-pages
 
# add .nojekyll to the root so that github won't 404 on content added to dirs
# that start with an underscore (_), such as our "_content" dir..
touch .nojekyll
 
# Add README
cat > README.md <<EOF
# GitHub Pages Cache
 
Nothing to see here. The contents of this branch are essentially a cache that's not intended to be viewed on github.com.
 
 
If you're looking to update our documentation, check the relevant development branch's 'docs/' dir.
 
For more information on how this documentation is built using Sphinx, Read the Docs, and GitHub Actions/Pages, see:
 
 * https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1
EOF
 
# copy the resulting html pages built from sphinx above to our new git repo
git add .
 
# commit all the new files
msg="Updating Docs for commit ${GITHUB_SHA} made on `date -d"@${SOURCE_DATE_EPOCH}" --iso-8601=seconds` from ${GITHUB_REF} by ${GITHUB_ACTOR}"
git commit -am "${msg}"
 
# overwrite the contents of the gh-pages branch on our github.com repo
git push deploy gh-pages --force
 
popd # return to main repo sandbox root

我写了一篇描述 how to run your own Read the Docs site on GitHub Pages 的文章，更详细地描述了上述文件。

Answer 2

我将@Michael Altfield 的解决方案改编成一个 GitHub 操作：

name: docs_pages_workflow 

on: 
  push:
    branches: [ main ]   

jobs:

  build_docs_job:
    runs-on: ubuntu-latest
    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

  steps:
    - name: Checkout
      uses: actions/checkout@v2.3.4

    - name: Set up Python
      uses: actions/setup-python@v2.2.1
      with:
        python-version: 3.9

    - name: Install dependencies
      run: |
        python -m pip install -U sphinx
        python -m pip install sphinx-rtd-theme
    
    - name: make the sphinx docs
      run: |
        make -C docs clean
        make -C docs html
              
    - name: Init new repo in dist folder and commit
      run: |
        cd docs/build/html/
        git init
        touch .nojekyll
        git add -A
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git commit -m 'deploy'

    - name: Force push to destination branch
      uses: ad-m/github-push-action@v0.5.0
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        branch: gh-pages
        force: true
        directory: ./docs/build/html

请注意，我的 Makefile 构建到 build 而不是 _build 目录。 directory: 的最后一行是说从我们刚刚创建新的 Git 存储库的 .docs/build/html 目录推送。这避免了他的 rsync 和 pushd 命令。否则逻辑遵循@Michael Altfield 的解决方案。

如何使用 GitHub 页面自行托管阅读文档

How to self-host Read the Docs using GitHub Pages

continuous-integration

github

gitlab

read-the-docs