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 sphin-incrbuild should be available. Use need to replace their sphinx-build command to sphin-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 sphin-incrbuild via --cache, and upload the cache after build finished, in pseudocode:

- run: restore /tmp/cache
- run: sphinx-incrbuild --cache /tmp/cache <other Sphinx options...>
- run: upload /tmp/cache

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