Repository navigation
ci(docs): check links on the built site and repair existing ones - #777
bartoszmajsak wants to merge 4 commits into
Conversation
Docusaurus checks Markdown links at build time, but raw <a href> tags, anchors and external URLs reach the live site unchecked (kserve#695, kserve#776). Scan the production build as GitHub Pages serves it, and fail PRs only on failures that a build of the base does not have. A nightly audit keeps one issue, with the verification, history and triage vendored from kserve/kserve#6568. Signed-off-by: Bartosz Majsak <bartosz.majsak@gmail.com>
The gRPC template linked message A.B as #a-b, but Docusaurus slugs that heading to #ab, and it linked scalars to a table the page never had. crd-ref-docs linked Knative, Gateway API, GIE and KEDA types to sections that don't exist, and listed KServe types it never renders. Signed-off-by: Bartosz Majsak <bartosz.majsak@gmail.com> (cherry picked from commit c09a124c467c2b1b0f0f8995344000ac85bf63ff)
Self links to /website/master, mkdocs-era repository paths and renamed headings stopped resolving, and Markdown link URLs cannot embed <ActiveDocsVersion />, so release links rendered as tree/release-. Upstream pages moved or were removed (llm-d, vLLM, Knative, Kubeflow). OIP REST anchors from the upstream spec get expiring exceptions. Signed-off-by: Bartosz Majsak <bartosz.majsak@gmail.com>
👷 Deploy request for elastic-nobel-0aef7a pending review.Visit the deploys page to approve it
|
[Medium impact] The latest changes appear safe to merge. SummaryAdds checks for links in the built website and repairs links across current and versioned docs.
|
| | [Inspur](https://www.inspur.com/) | [Qingshan Chen](https://github.com/iamlovingit) | | | | ||
| | [Intuit](https://www.intuit.com/) | [Rachit Chauhan](https://github.com/rachitchauhan43) | | | | ||
| | [Kubeflow](https://www.kubeflow.org/) | [Yuan Tang](https://github.com/terrytangyuan) | [KServe Integration](https://www.kubeflow.org/docs/external-add-ons/kserve/) | Production | | ||
| | [Kubeflow](https://www.kubeflow.org/) | [Yuan Tang](https://github.com/terrytangyuan) | [KServe Integration](https://www.kubeflow.org/docs/ecosystem/kserve/) | Production | |
There was a problem hiding this comment.
Not a tab, just spaces - the new URL is shorter, so the padding keeps the column as wide as in the other rows.
| | [Red Hat](https://www.redhat.com/) | [Yuan Tang](https://github.com/terrytangyuan) | [Red Hat OpenShift AI](https://www.redhat.com/en/technologies/cloud-computing/openshift/openshift-ai), [KubeCon Talk](https://youtu.be/oVJXnlrSuDE?si=doDtv2Ajcvg4fzH7), [Blogpost](https://developers.redhat.com/articles/2024/03/15/empower-conversational-ai-scale-kserve) | Production | | ||
| | [SAP](https://www.sap.com) | [Lize Cai](https://github.com/lizzzcai) | [Adopter Interview with CNCF](https://github.com/cncf/toc/blob/main/projects/kserve/kserve-adopter-interview-sap.md) | Production | | ||
| | [Seldon](https://www.seldon.io/) | [Alex Housley](https://github.com/ahousley) | | | | ||
| | [Seldon](https://seldon.io/) | [Alex Housley](https://github.com/ahousley) | | | |
There was a problem hiding this comment.
Same here, padding for the shorter URL.
| ``` | ||
|
|
||
| You can find [the code example](https://github.com/kserve/kserve/tree/release-<ActiveDocsVersion />/docs/samples/v1beta1/triton/torchscript/image_transformer_v2) and [Dockerfile](https://github.com/kserve/kserve/blob/release-<ActiveDocsVersion />/docs/samples/v1beta1/triton/torchscript/transformer.Dockerfile) in the KServe repository. | ||
| You can find [the code example](https://github.com/kserve/kserve/tree/v0.9.0/docs/samples/v1beta1/triton/torchscript/image_transformer_v2) and [Dockerfile](https://github.com/kserve/kserve/blob/v0.9.0/docs/samples/v1beta1/triton/torchscript/transformer.Dockerfile) in the KServe repository. |
There was a problem hiding this comment.
any reason to pin to a specific version?
There was a problem hiding this comment.
The sample was removed from kserve in kserve/kserve#2629, so it is gone since v0.10.0 and v0.9.0 is the last tag that has it. Before this change the link rendered as a truncated tree/release-, so it never worked. We could also drop the sentence, since the code is inline above. WDYT?
| ## References | ||
|
|
||
| * [Modelcar Design document](https://docs.google.com/document/d/1Bs4fnP8rhPMaoPoLSYVvuRq-z9vkGPQ0rKbmfH4I7js/edit#heading=h.xw1gqgyqs5b) | ||
| * [Modelcar Design document (archived)](https://web.archive.org/web/20241118173548if_/https://docs.google.com/document/d/1Bs4fnP8rhPMaoPoLSYVvuRq-z9vkGPQ0rKbmfH4I7js/edit) |
There was a problem hiding this comment.
I would keep it. The original doc is deleted (Google returns 410), and the archived copy still has the full design. Happy to drop it if you would rather not link an archive though.
A rendered href such as `https://host.invalid:99999/doc` raised from the GitHub target parser and stopped the whole scan. It is now a malformed URL finding on its page, like an unclosed IPv6 bracket. Signed-off-by: Bartosz Majsak <bartosz.majsak@gmail.com>
Docusaurus only checks Markdown links and
<Link>. Raw<a href>, anchors (onBrokenAnchorsiswarn), external URLs and self links like/website/master/...go unchecked, so they break on the live site first. An audit of the current site found 101 broken internal links, 7 missing GitHub targets and 29 external 404s across six doc versions.Proposed Changes
frameworks/sklearn/sklearnfail. Existing debt never fails a PR.On a fork at this head, the PR run checks 42 new external URLs with no failures, and the nightly audit covers 964 pages and 1096 external URLs with no internal or GitHub failures. Six injected faults each fail the gate; a text edit on a page with debt and
docs:version 0.21pass.Seven external 404s stay, in generated SDK reference pages built from upstream docstrings. Two go away with the next SDK doc regen after kserve/kserve#6568; the nightly issue picks up the rest after seven days.
Open question: 8 anchors on the OIP REST pages only exist in upstream
inference_rest.mdand carry expiring exceptions. Fix them in open-inference-protocol (open_inference_rest.yamllines 80, 104 and 138), or post-process the generated pages here?Repair details
A.Bas#a-b, but Docusaurus slugs the heading#ab. crd-ref-docs linked Knative, Gateway API and KEDA types to sections that don't exist; they now point to pkg.go.dev.release-<ActiveDocsVersion />inside a link URL rendered as a truncatedtree/release-. Those links now use a small component./website/master/...self links, mkdocs-erakserve/website/tree/main/docspaths, renamed anchors and moved external pages are updated acrossdocs/, allversioned_docsand the blog.Follow-up to #695 and #776.