Skip to content

doc: add checks on docs integration - #1480

Open
elijahgreenstein wants to merge 1 commit into
canonical:mainfrom
elijahgreenstein:integration-tests
Open

doc: add checks on docs integration#1480
elijahgreenstein wants to merge 1 commit into
canonical:mainfrom
elijahgreenstein:integration-tests

Conversation

@elijahgreenstein

Copy link
Copy Markdown
Contributor

The docs integration often depends on overwriting files in the upstream LXD, MicroCeph, and MicroOVN repositories. If those files move or if configuration settings change, it is possible for the build to complete successfully, but with incorrect settings or other issues.

This commit separates the integrate process in the docs Makefile into several steps:

  • integrate-pull clones the upstream repositories and pins them to specific commits
  • integrate-precheck (depends on integrate-pull) confirms that various files are located where expected, and are configured as expected
  • integrate (depends on integrate-precheck) copies and overwrites files, and builds the documentation

The docs integration often depends on overwriting files in the upstream
LXD, MicroCeph, and MicroOVN repositories. If those files move or if
configuration settings change, it is possible for the build to complete
successfully, but with incorrect settings or other issues.

This commit separates the `integrate` process in the docs Makefile into
several steps:

- `integrate-pull` clones the upstream repositories and pins them to
  specific commits
- `integrate-precheck` (depends on `integrate-pull`) confirms that
  various files are located where expected, and are configured as
  expected
- `integrate` (depends on `integrate-precheck`) copies and overwrites
  files, and builds the documentation

Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
@elijahgreenstein
elijahgreenstein marked this pull request as draft August 6, 2026 20:40
@elijahgreenstein
elijahgreenstein marked this pull request as ready for review August 6, 2026 20:40
@elijahgreenstein

Copy link
Copy Markdown
Contributor Author

Related to #1475, with regard to the noindex checks.

@elijahgreenstein

Copy link
Copy Markdown
Contributor Author

@roosterfish -- these are some checks intended to catch changes to the upstream repositories before building and serving the integrated documentation. As you can see, I've currently set these up so that the build fails if there are any issues. However, I also considered setting the checks up as make target that could be triggered as a GitHub workflow, such that the build could complete regardless of the status of the checks. Do you have any thoughts on these two approaches? Ultimately I decided on having the build fail. If, for example, the MicroOVN header template is moved to a new directory, it's possible for the build to complete but the built docs to be set up incorrectly. I believe this was the kind of issue that we had with MicroCeph in the MicroCloud 2 docs that was resolved with this PR: #1454.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant