docs: Makefile, check-build.sh clean-ups and perf improvements #28161
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
qmonnet
added
area/documentation
qmonnet
changed the title
|
/test |
The Makefile for the documentation makes sure that the docs-builder image is always present and up-to-date before building the docs. To do so, it simply rebuilds the image, every time. This is efficient to make sure the image is up-to-date, but not that much in terms of build duration. Let's make it possible to skip that step if the user is confident their image is present and up-to-date. Signed-off-by: Quentin Monnet <quentin@isovalent.com>
Allow users to set the INCREMENTAL environment variable to avoid passing the "-E" option to Sphinx when skipping the linters. This way, we can have Sphinx do incremental builds instead of re-reading and re-writing all files. This can be used for quick iterations on a local setup. There is no need to make "-E" conditional for the spell checker run, given that the spell checker seems to always re-read all files anyway. Signed-off-by: Quentin Monnet <quentin@isovalent.com>
The documentation build targets, including html, have a dependency on update-helm-values. There is no clear reason for that: this seems to be for historical reasons. - Initially, the dependency was on $(HELM_VALUES), because the file with Helm values had not been committed to the Git repo at the time, so we needed to ensure that it was generated first. - When reorganising checks for Helm values in 6167f8a ("docs: check updates for the Helm reference"), we replaced it with "update-helm-values" which looked cleaner; but we don't need to run the _check_ at this stage, only to make sure the _file_ itself is available. Now that the file is part of the repository, there's no need to check for its existence, and we can simply remove the target dependency (to align it with other files that receive automatic updates, such as codeowners.rst or crdlist.rst). Signed-off-by: Quentin Monnet <quentin@isovalent.com>
Let's make sure all Makefile targets are properly documented, and nicely displayed when running "make help". Signed-off-by: Quentin Monnet <quentin@isovalent.com>
Move around targets inside of Documentation/Makefile to have them
displayed in a more sensible order on "make help".
$ make help
Usage:
make <target>
Targets (default: "html")
Development Images
base-image Build the docs-base image for updating the requirements.txt file.
builder-image Build the docs-builder image for rendering and checking the documentation.
Auto-generated Contents Updates and Validation
api-flaggen Update the table of API flags restrictions.
update-cmdref Update the command reference documents (agent, bugtool, operators, etc.).
update-codeowners Update the description of the code owner teams.
update-crdlist Update the list of CRDs.
update-helm-values Update the Helm reference documentation.
check Validate command and Helm references, policy examples, and others.
Build
html Check documentation and render it under the specified format.
epub Check documentation and render it under the specified format.
latex Check documentation and render it under the specified format.
live-preview Build and serve the documentation locally.
Development
update-requirements Regenerate the requirements.txt file from requirements-min/requirements.txt.
clean Clean up all artefacts from documentation.
help Display help for the Makefile.
Also add target update-cmdref to .PHONY.
Signed-off-by: Quentin Monnet <quentin@isovalent.com>
Since commit 944dddf ("docs: Symlink (instead of copying) the API reference"), we symlink the _api/ directory (from ../api) instead of copying it. So there's nothing to clean on that side on "make clean", otherwise we lose the link. Fixes: 944dddf ("docs: Symlink (instead of copying) the API reference") Signed-off-by: Quentin Monnet <quentin@isovalent.com>
qmonnet
force-pushed
the
pr/doc-makefile-cleanup
branch
from
edaf26a
to
9e20cdf
Compare
|
/test |
zacharysarah
approved these changes
Sep 14, 2023
There was a problem hiding this comment.
Thanks for this, @qmonnet. 🌟 I tested changes locally, and make render-docs SKIP_BUILDER_IMAGE=1 does indeed run much more quickly now. ⏩
maintainer-s-little-helper
bot
added
the
ready-to-merge
doniacld
added
backport-pending/1.13
giorio94
added
backport-pending/1.14
aanm
added
backport-done/1.14
This was referenced Oct 17, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Some users find that
make render-docsormake test-docsare too slow for quickly iterating over local changes. This PR contains a few commits to improve things. The first run of either command will still take time, but provided thedocs-builderimage is present on the system and up-to-date, subsequent runs ofmake render-docs SKIP_BUILDER_IMAGE=1ormake test-docs SKIP_LINT=1 INCREMENTAL=1 SKIP_BUILDER_IMAGE=1should go faster. See individual commits for details.This PR also contains some fixes and clean-ups, in particular for the output of
make -C Documentation help.Cc @networkop