使用GitHub操作发布文档 [英] Using github actions to publish documentation
问题描述
我考虑的:
- GitHub提供GitHub页面来托管
master
分支或专用gh-pages
分支上的文档,但这意味着提交构建构件 - 我还可以让
readthedocs
通过WebHook为我构建和托管文档,但这意味着学习如何在尝试整合github-actions
中与我的项目相关的所有内容的时间点配置另一个工具
我已经有了一个适合我的文档构建过程(使用sphinx
作为构建器),并且我还可以在本地测试,所以我宁愿只利用它。它设置了所有的规则,并在艺术品中放置了一些静态html
-它只是在任何地方都不会被服务。在我的项目的所有其他部署配置都存在的工作流中处理它,感觉比将它分散在不同的工具或GitHub特定的选项上要好。
市场中是否已有允许我执行此类操作的操作?
name: CI
on: [push]
jobs:
... # do stuff like building my-project-v1.2.3.whl, testing, etc.
release_docs:
steps:
- uses: actions/sphinx-to-pages@v1 # I wish this existed
with:
dependencies:
- some-sphinx-extension
- dist/my-project*.whl
apidoc_args:
- "--no-toc"
- "--module-first"
- "-o docs/autodoc"
- "src/my-project"
build-args:
- "docs"
- "public" # the content of this folder will then be served at
# https://my_gh_name.github.io/my_project/
换句话说,我仍然希望能够控制构建如何进行以及将构件放在哪里,但不需要处理与readthedocs
或github-pages
的交互。
#我尝试的操作
❌deploy-to-github-pages:在npm容器中运行文档构建-将不方便使其与Python和Shinx一起工作
❌gh-pages-for-github-action:无文档
❌gh-pages-deploy:似乎以Jekyll这样的主机环境为目标,而不是静态内容,并且对YML语法的正确用法尚未记录-我尝试了一些,但无法正常工作
❌github-pages-deploy:看起来不错,但YML语法的正确用法尚未记录
✅github-pages:需要自定义PAT才能触发重建(这很不方便)和uploads broken html(这很糟糕,但可能是我的错)
✅deploy-action-for-github-pages:也有效,并且在日志中看起来更干净一些。虽然与上面的解决方案有相同的限制,但它需要PAT,并且提供的html仍然是损坏的。
在动作市场上搜索github+pages时的其他11个结果看起来都像是他们想要使用自己的构建器,遗憾的是,这个构建器从来都不是狮身人面像。
推荐答案
在使用pip(requirements.txt
)、pipeenv或POLITE管理sphinx
的情况下,我们可以将文档部署到GitHub页面,如下所示。对于其他基于Python的静态站点生成器,如Pelcan和MkDocs,工作流的工作方式也是一样的。下面是一个简单的MkDocs示例。我们只需将工作流添加为.github/workflows/gh-pages.yml
有关更多选项,请参阅最新自述文件:peaceiris/actions-gh-pages: GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.
name: github pages
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v2
- name: Setup Python
uses: actions/setup-python@v2
with:
python-version: '3.8'
- name: Upgrade pip
run: |
# install pip=>20.1 to use "pip cache dir"
python3 -m pip install --upgrade pip
- name: Get pip cache dir
id: pip-cache
run: echo "::set-output name=dir::$(pip cache dir)"
- name: Cache dependencies
uses: actions/cache@v2
with:
path: ${{ steps.pip-cache.outputs.dir }}
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: python3 -m pip install -r ./requirements.txt
- run: mkdocs build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./site
这篇关于使用GitHub操作发布文档的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!