CI (docs): Reusable Mintlify docs checks for integrations repos#106258
CI (docs): Reusable Mintlify docs checks for integrations repos#106258Blargian wants to merge 7 commits into
Conversation
Remove trailing hyphen from anchor to match external links in clickhouse-docs repo. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The two example result blocks were not regenerated after the queries were changed to `ORDER BY VisitID`, so the displayed rows did not match what a reader running the query would see. Regenerate both blocks in `VisitID` order, and add `Goal.Serial` as a tie-breaker to the `ARRAY JOIN` example so the goals within a single visit are listed deterministically in array order. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Decouple the Mintlify docs check logic from Praktika so another repository (e.g. a language client whose docs are a slice of the larger site) can run the same checks without vendoring Praktika. - Add `ci/jobs/scripts/docs/mintlify_docs_check.py`, a self-contained driver that pulls the docs image, shallow/sparse-clones the aggregator docs repo (including `ci/jobs/scripts/docs` so shared check scripts come along), overlays one or more local folders, and runs the checks inside the image. The host only needs `docker`, `git` and `python3`; `mint` is provided by the image. The check definitions live in `DEFAULT_CHECKS` as the single source of truth. - Rewrite `ci/jobs/docs_job_mintlify.py` as a thin Praktika adapter that imports `DEFAULT_CHECKS` and runs them natively (it already runs inside the image), so new checks are declared in one place. - Add `ci/jobs/scripts/docs/check_readonly_copies.py` and `readonly_copies.json`, a one-way-sync guard that fails edits to docs folders whose canonical source lives in another repo and points contributors at that source. Wired into the Praktika job only (aggregator side); deliberately not part of `DEFAULT_CHECKS`. - Track `ci/jobs/scripts/docs` in the docs job digest so changes to the shared check scripts re-run the job. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Blargian
changed the title
|
Workflow [PR], commit [4b9d59d] Summary: ✅ AI ReviewSummaryThis PR makes the Mintlify docs checks reusable by moving the check list into a standalone driver, adding a read-only copied-docs guard, and updating the Missing context / blind spots
Findings
Tests
Final VerdictStatus: Minimum required action: make the standalone overlay reflect deletions from the consuming repo, then add a small regression check for that behavior. |
![clickhouse-gh[bot]](https://avatars.githubusercontent.com/in/928874?s=60&v=4){kind=small}
| parts = spec.split(":") | ||
| if len(parts) < 2: | ||
| raise ValueError(f"Invalid --overlay '{spec}'. Expected SRC:DEST[:mirror].") | ||
| mirror = len(parts) >= 3 and parts[2].lower() in ("1", "true", "mirror", "yes") |
There was a problem hiding this comment.
The standalone check should validate the exact docs slice from the consuming repo, but the default overlay mode is a merge. If a client repo deletes or renames a page, the old file from the cloned aggregator remains under dest, so mint validate and mint broken-links can pass even though the next sync would remove that page and potentially break the site. The help/example path does not require :mirror, so this is the mode consumers are likely to use.
Please make replacement the default for --overlay (or require an explicit mode and use mirror in the documented invocation), so deletions in the source repo are visible to the checks.
1 participant
Structures the Mintlify docs check such that it can be easily run standalone without Praktika in other repos. The motivation for this is to enable us to easily run the same Mintlify docs checks in this repository in language client repos.
Context:
Our integrations team would like to keep docs close to the source code so they can make docs updates alongside code changes. Currently the docs are kept in clickhouse-docs repo and it's necessary to context switch to make docs updates.
With the Mintlify migration, beginning with clickhouse-connect: ClickHouse/clickhouse-connect#768, we will move language client docs back into their own repositories. As part of the language client CI any changes to the docs will run the Mintlify docs check in ClickHouse/ClickHouse in the docs_builder container. If all checks pass the PR merges. GitHub releases of the client trigger a workflow which 'syncs' the docs to copies of them in this repo.
We want the sync to be unidirectional, so there is a check added to this repository to fail the docs check with an error message pointing to the canonical source if someone tries to make the updates in ClickHouse/ClickHouse.
Changelog category (leave one):
Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):
...