使用git sparse-checkout加快文档构建速度¶
¥Using git sparse-checkout for faster documentation builds¶
利用 GitHub Actions 中的 git sparse-checkout，我们可以加快存储库中的文档构建速度，将签出时间从 20 到 30 秒缩短到仅 2 秒。
¥Leveraging git sparse-checkout in GitHub Actions enabled us to speed up documentation builds in our repository, cutting checkout times from 20 to 30 seconds to just 2 seconds.
在持续集成 (CI) 工作流中，开发一种高效的文档构建方法至关重要，尤其是在像我们这样拥有数千条提交记录的大型代码库中工作时。当然，我们希望快速高效地构建文档，确保快速高效的工作流程。在使用出色的git-committers和git-revision-date-localized插件在每页底部显示文档贡献者和日期时，我们需要设置fetch-depth: 0 ，这导致代码库的检出时间需要 20 到 30 秒。通过利用GitHub Actions中的git sparse-checkout功能，检出时间缩短至 2 秒。
¥Developing an efficient approach to build documentation in CI workflows is essential, especially when working in large repositories with thousands of commits, like ours. Of course, we want to build documentation quickly and efficiently, ensuring fast and productive workflows. When using both the wonderful git-committers and git-revision-date-localized plugins to display document contributors and dates at the bottom of each page, we are required to set fetch-depth: 0, which resulted in checkout times of 20 to 30 seconds on our repository. By leveraging git sparse-checkout within GitHub Actions, check out time was brought down to 2 seconds.
入门¶
¥A Primer¶
git sparse-checkout允许您仅检出存储库中的部分文件，这对于大型存储库非常有用，因为完整检出需要很长时间，并且包含许多与构建文档无关的文件。
¥git sparse-checkout allows you to check out only a subset of the files in a repository, making it incredibly useful for large repositories where a full checkout takes long and includes many files that are not relevant when building documentation.
GitHub Actions¶
¥GitHub Actions¶
要在GitHub Actions中启用git sparse-checkout并确保仅构建所需的文档，请将以下行添加到工作流文件中：
¥To enable git sparse-checkout within GitHub Actions and ensure that you are only building the documentation that you need, add the following lines to your workflow file:
git sparse-checkout始终会检出仓库根目录中的所有文件。这意味着，无论为 sparse checkout 指定了什么路径或目录，位于仓库根目录中的文件始终会包含在检出过程中。
¥git sparse-checkout always checks out all files residing in the repository’s root. This means that regardless of the specified paths or directories for sparse checkout, the files located in the root of the repository will always be included in the checkout process.
因此，您只需指定构建文档所需的目录即可。在我们的例子中，我们只需要docs和includes文件夹，但如果您需要其他目录，只需将它们添加到列表末尾即可。GitHub Actions的完整示例工作流程：
¥Thus, you only need to specify the directories that are necessary for building documentation. In our case, we only need the docs and includes folders, but if you need additional directories, you can just add them to the end of the list. A complete example workflow for GitHub Actions:
name: documentation
on:
push:
branches:
- master
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
sparse-checkout: |
docs
includes
- uses: actions/setup-python@v4
with:
python-version: 3.x
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
结论¶
¥Conclusion¶
就这些！我们对结果非常满意，希望这也能帮助您加快在GitHub Actions中构建文档的速度。和往常一样，欢迎在下面的评论区分享您的想法和经验。
¥That's all there is! We're super happy with the results and hope that this will help you to speed up your documentation builds in GitHub Actions as well. As always, feel free to share your thoughts and experiences in the comments below.