sphinxnotes-incrbuild¶

Introduction¶

As we know, Sphinx supports incremental HTML build, and it works well locally. But for CI/CD, the environment is usually brand new, which causes Sphinx always to rebuild everything.

The project wraps sphinx-build and ensures the environment is “incremental build” -able before running the real sphinx-build.

Getting Started¶

Note

For most users, please go directly to GitHub Actions and GitLab CI.

First, downloading extension from PyPI:

$ pip install sphinxnotes-incrbuild

After installation, command sphinxnotes-incrbuild should be available. User need to replace their sphinx-build command to sphinxnotes-incrbuild.

All arguments of sphin-incrbuild are same to sphinx-build except:

--cache CACHE:: path to directory that will be cached by CI/CD

Use should use CI/CD’s Cache mechanism, restore cache file to cache directory pass the directory to sphinxnotes-incrbuild via --cache, and save the cache after build finished, in pseudocode:

- restore_cache:
  key: /tmp/sphinxnotes-incrbuild
- run: sphinx-incrbuild <SOURCEDIR> <OUTPUTDIR>
- save_cache:
  key: /tmp/sphinxnotes-incrbuild

Users who use make html to build documentation should passing the override the SPHINXBUILD:

- restore_cache:
  key: /tmp/sphinxnotes-incrbuild
- run: make html SPHINXBUILD="python -msphinxnotes.incrbuild"
- save_cache:
  key: /tmp/sphinxnotes-incrbuild

GitHub Actions¶

sphinxnotes-incrbuild is already integrated into action sphinx-notes/pages@v3, just set cache: true to enable incremental build.

- id: deployment
  uses: sphinx-notes/pages@v3
  with:
    cache: true

GitLab CI¶

TODO

Contents¶

Contents

Change Log

The Sphinx Notes Project¶

The project is developed by Shengyu Zhang, as part of The Sphinx Notes Project.

The Sphinx Notes Project