RTDスタイルのgithubページのパッケージドキュメントを展開します.
24262 ワード
概要
近年では、多くのPythonパッケージはReadtheDocsのようなサードパーティ製のサービスからGithubページにドキュメントのパイプラインを動かしましたが、いくつかの有用な機能がそのプロセスに欠けていました.
このポストでは、Githubアクションのために-ほぼ完全なRTDパイプラインを書く方法について説明します.
機能
pip and conda 依存ファイル./branches/<branch> . /tags/<tag>/pull/<number> ラベル経由で.gh-pages ). /latest or /stable (デフォルト:/latest ). /stable サブドメインへのサブドメインstable 枝(存在する場合).サポートされない
ライブデモ
ワークフロー
引き金
パイプラインは次のイベントで起動する必要があります.
main と他の指定された枝.pull_request_target イベント秘密を共有できるように.この動作は、セキュリティ上の理由からジョブレベルで制約されます.on:
push:
branches:
- main # default branch
- new-feature # extra branches to build
tags:
- 'v[0-9]+.[0-9]+.[0-9]+' # semantic versions
pull_request_target: # pull request build
branches:
- '*'
types:
- opened
- synchronize
- reopened
- labeled # requires the `build-docs` label
workflow_dispatch: # manual trigger
branches:
- '*'
パラメータ
これらは、あなたが
env セクション.PYTHON : Pythonのバージョン(デフォルト:3.9 ) PKGS_FILE : エーtxt or yml ファイルを使いたい場合にconda or pip 環境を配備するにはBUILD_CMD : sphinxビルドコマンド(デフォルト:cd docs && make html ). DEPLOY_BRANCH : Githubページの枝(デフォルト:gh-pages ) ROOT_REDIRECT : ルートURLをリダイレクトする/latest or /stable (デフォルト:/latest , デフォルトの枝のビルド).env:
PYTHON: 3.9
PKGS_FILE: docs/requirements.txt # .txt (`pip`) or .yml (`conda`) file
BUILD_CMD: cd docs/ && make html
DEPLOY_BRANCH: gh-pages # target branch to deploy _build/html
ROOT_REDIRECT: latest # `latest` or `stable`
The
build ジョブ秘密を安全に共有する
The
if 上の条件build ジョブ制約pull_request_target トリガーを必要とするbuild-docs ラベルトリガジョブ.リポジトリへの書き込みアクセスを持つ人々だけが、プルリクエストをラベルすることができますので、これは信頼できる貢献者と安全に秘密を共有できるように素晴らしい方法です.
jobs:
build:
if: github.event_name == 'push' ||
github.event_name == 'workflow_dispatch' ||
(github.event_name == 'pull_request_target' &&
contains(github.event.pull_request.labels.*.name, 'build-docs'))
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
if: github.event_name != 'pull_request_target'
- name: Checkout pull request ${{ github.event.number }}
uses: actions/[email protected]
with:
ref: ${{ github.event.pull_request.head.sha }}
if: github.event_name == 'pull_request_target'
Makefile ) すべての種類のセキュリティの問題につながることができますので、それらをラベル付けする前に信頼できない貢献者のPRSを確認してください.For more information, see: "Keeping your GitHub Actions and workflows secure"
既存の支店をチェック
これは後で使用する展開ブランチと安定ブランチの存在をチェックします.
- name: Check branches
run: |
CHECK_DEPLOY=$(git ls-remote --heads origin refs/heads/${{ env.DEPLOY_BRANCH }})
CHECK_STABLE=$(git ls-remote --heads origin refs/heads/stable)
echo "::set-output name=DEPLOY::$(! [[ -z $CHECK_DEPLOY ]] && echo 'true' || echo 'false')"
echo "::set-output name=STABLE::$(! [[ -z $CHECK_STABLE ]] && echo 'true' || echo 'false')"
cat $GITHUB_ENV
id: check-branches
環境設定
次のステップでは、MambaForgeは、カスタムMinicondaインストーラを設定します
mamba パッケージマネージャー.そして、与えられたファイルの拡張に応じて環境を更新する.
- name: Setup Mambaforge
uses: conda-incubator/[email protected]
with:
miniforge-variant: Mambaforge
miniforge-version: latest
activate-environment: sphinx
python-version: ${{ env.PYTHON }}
use-mamba: true
- name: Install packages
run: |
if [[ ${{ env.PKGS_FILE }} == *.txt ]]; then
pip install -r ${{ env.PKGS_FILE }}
elif [[ ${{ env.PKGS_FILE }} == *.yml ]] || [[ ${{ env.PKGS_FILE }} == *.yaml ]]; then
mamba env update -n sphinx -f ${{ env.PKGS_FILE }}
else
echo "Unsupported file extension"
exit 1
fi
ビルドと配備
サイトの展開がイベントトリガーの組み合わせに依存するので、私はそれほど複雑でないことを書く必要がありました
bash 適切に目的地パスを扱うスクリプト.そして
peaceiris/actions-gh-pages アクションは結果のサイトを展開する$DEST_DIR 変数. - name: Build documentation
run: ${{ env.BUILD_CMD }}
- name: Set destination directory
run: |
BRANCH=$(echo ${GITHUB_REF#refs/heads/})
TAG=$(echo ${GITHUB_REF#refs/tags/})
if [[ $EVENT == push ]] || [[ $EVENT == workflow_dispatch ]]; then
if [[ -z $TAG ]] || [[ $TAG == $GITHUB_REF ]]; then
if [[ $BRANCH == $DEFAULT ]]; then
echo "DEST_DIR=latest" >> $GITHUB_ENV
else
echo "DEST_DIR=branch/$BRANCH" >> $GITHUB_ENV
fi
elif [[ ! -z $TAG ]]; then
echo "DEST_DIR=tag/$TAG" >> $GITHUB_ENV
else
echo "Unexpected ref $GITHUB_REF"
exit 1
fi
elif [[ $EVENT == pull_request_target ]]; then
echo "DEST_DIR=pull/$PR" >> $GITHUB_ENV
else
echo "Unexpected event trigger $EVENT"
exit 1
fi
cat $GITHUB_ENV
env:
DEFAULT: ${{ github.event.repository.default_branch }}
EVENT: ${{ github.event_name }}
PR: ${{ github.event.number }}
- name: Deploy ${{ env.DEST_DIR }}
uses: peaceiris/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_branch: ${{ env.DEPLOY_BRANCH }}
publish_dir: ./docs/_build/html
destination_dir: ${{ env.DEST_DIR }}
user_name: 'github-actions[bot]'
user_email: 'github-actions[bot]@users.noreply.github.com'
リダイレクトする
最後に、メインURLと
/stable 上記のパラメータに従ってサブドメイン. - name: Redirect root
run: |
mkdir redirects && cd redirects
echo '<head>' >> index.html
echo ' <meta http-equiv="Refresh" content="0; url='/${{ github.event.repository.name }}/${{ env.ROOT_REDIRECT }}'"/>' >> index.html
echo '</head>' >> index.html
- name: Redirect stable
run: |
git fetch origin
git checkout ${{ env.DEPLOY_BRANCH }}
if [[ -d tag ]] && [[ ! -z $(ls -A tag) ]]; then
LAST_TAG=$(ls -d tag/*/ | sort -V | tail -n 1)
mv $LAST_TAG /tmp/stable
git checkout -
mv /tmp/stable redirects
ls -lR redirects
else
echo "No tags to deploy"
fi
if: steps.check-branches.outputs.DEPLOY == 'true' && steps.check-branches.outputs.STABLE == 'false'
- name: Deploy redirects
uses: peaceiris/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./redirects
keep_files: true
user_name: 'github-actions[bot]'
user_email: 'github-actions[bot]@users.noreply.github.com'
The
clean ワークフロー別のワークフローは、マージされた/閉じられたプル要求、削除された分岐またはタグからページの除去を扱います.
# If you use this workflow, please acknowledge it
#
# author: Ezequiel Pássaro (@epassaro)
# organization: TARDIS-SN (@tardis-sn)
# license: MIT
name: clean-docs
on:
delete:
branches: # remove deleted branches or tags
- '*'
tag:
- '*'
pull_request_target: # remove closed or merged pull requests
branches:
- '*'
types:
- closed
env:
DEPLOY_BRANCH: gh-pages # deployed docs branch
jobs:
clean:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- name: Set folder to delete
run: |
if [[ $EVENT == delete ]]; then
echo "DEST_DIR=$EVENT_TYPE/$EVENT_REF" >> $GITHUB_ENV
elif [[ $EVENT == pull_request_target ]]; then
echo "DEST_DIR=pull/$PR" >> $GITHUB_ENV
else
echo "Unexpected event trigger $EVENT"
exit 1
fi
cat $GITHUB_ENV
env:
EVENT: ${{ github.event_name }}
EVENT_REF: ${{ github.event.ref }}
EVENT_TYPE: ${{ github.event.ref_type }}
PR: ${{ github.event.number }}
- name: Clean ${{ env.DEST_DIR }}
run: |
git fetch origin ${{ env.DEPLOY_BRANCH }}
git checkout ${{ env.DEPLOY_BRANCH }}
git config user.name github-actions[bot]
git config user.email github-actions[bot]@users.noreply.github.com
if [[ -d $DEST_DIR ]]; then
git rm -rf $DEST_DIR
git commit -m "clean $DEST_DIR"
git push
else
echo "$DEST_DIR does not exist"
fi
コードを得る
epassaro / actions-rtd-workflow
GITHUBアクションのためのRTD類似ドキュメンテーションパイプライン
ワークフロー
GITHUBアクションのためのRTD類似ドキュメンテーションパイプライン
機能
pip and conda 依存ファイル./branches/<branch> . /tags/<tag> . /pull/<number> ラベル経由で.gh-pages ). /latest or /stable (デフォルト:/latest ). /stable サブドメインを最新のsemverタグ、あるいは安定したブランチ(存在する場合).マルチ言語ビルド.
ライブデモ
Reference
この問題について(RTDスタイルのgithubページのパッケージドキュメントを展開します.), 我々は、より多くの情報をここで見つけました https://dev.to/epassaro/deploy-your-package-documentation-on-github-pages-in-the-rtd-style-preview-prs-and-more-ogfテキストは自由に共有またはコピーできます。ただし、このドキュメントのURLは参考URLとして残しておいてください。
Collection and Share based on the CC Protocol