Implement doc checkers

[listx]

Reference: kubernetes/test-infra#24821 (comment)

As per the design doc, we should implement automated checkers to make sure we uphold minimum quality standard for both existing documentation as well as newly proposed documentation.

There have been some discussions in the design doc already, but feel free to comment on here about which checker(s) to implement first.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue or PR with /reopen
• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue.

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue or PR with /reopen
• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[jihoon-seo]

/reopen
/lifecycle frozen

Here are tools I saw:

1. K8s doc's Internal link checking tool

According to the doc, the tool

• Builds the site and generates output HTML in the /public directory of your local kubernetes/website repository
• Pulls the wdjp/htmltest Docker image
• Mounts your local kubernetes/website repository to the Docker image
• Scans the files generated in the /public directory and provides command line output when it encounters broken internal links

and its workflow seems similar to the current link checker in this Prow doc repo.

prow/site/Makefile

Lines 26 to 27 in 0d8946d

	check-broken-links:
	find ./public -name "*.html" -print0 | sort -z | xargs -0 ./check-broken-links.sh

prow/site/check-broken-links.sh

Lines 22 to 30 in 0d8946d

	for file; do
	if [[ "${file}" =~ /_print/index.html ]]; then
	echo "skipping file ${file}"
	continue
	fi
	echo "checking file ${file}"
	htmltest -c .htmltest.yml "${file}" | sed 's/^/ /'
	echo
	done

---

2. K8s doc's linkchecker.py

While the above linkcheckers analyze whether the links in the Hugo-generated HTML files are working or not (404, ...),
this linkchecker performs sort of static analysis on markdown files.

---

And yes, it would be great to implement a new linkchecking Prow workflow

• for every PR, and/or
• executed periodically

[k8s-ci-robot]

@jihoon-seo: You can't reopen an issue/PR unless you authored it or you are a collaborator.

In response to this:

/reopen
/lifecycle frozen

Here are tools I saw:

1. K8s doc's Internal link checking tool

According to the doc, the tool

• Builds the site and generates output HTML in the /public directory of your local kubernetes/website repository
• Pulls the wdjp/htmltest Docker image
• Mounts your local kubernetes/website repository to the Docker image
• Scans the files generated in the /public directory and provides command line output when it encounters broken internal links

and its workflow seems similar to the current link checker in this Prow doc repo.

prow/site/Makefile

Lines 26 to 27 in 0d8946d

	check-broken-links:
	find ./public -name "*.html" -print0 | sort -z | xargs -0 ./check-broken-links.sh

prow/site/check-broken-links.sh

Lines 22 to 30 in 0d8946d

	for file; do
	if [[ "${file}" =~ /_print/index.html ]]; then
	echo "skipping file ${file}"
	continue
	fi
	echo "checking file ${file}"
	htmltest -c .htmltest.yml "${file}" | sed 's/^/ /'
	echo
	done

---

2. K8s doc's linkchecker.py

While the above linkcheckers analyze whether the links in the Hugo-generated HTML files are working or not (404, ...),
this linkchecker performs sort of static analysis on markdown files.

---

And yes, it would be great to implement a new linkchecking Prow workflow

• for every PR, and/or
• executed periodically

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[petr-muller]

/reopen

Does not feel like an issue that should rot - either we think this is useful, or we should explicitly decide we don't want that.

[k8s-ci-robot]

@petr-muller: Reopened this issue.

In response to this:

/reopen

Does not feel like an issue that should rot - either we think this is useful, or we should explicitly decide we don't want that.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[listx]

I think the first option (https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools/linkchecker) could be adopted. It is simpler as it already uses the same underlying tool (htmltest) that we currently use.

The first step is to add it as a CI job (either the same link checker as used in kubernetes/website or the existing Make rule we have). I don't think it makes sense to add it as a presubmit as links can break sporadically. Probably running the job 2x a day would be good so that we can get some signal that all links are OK.