website/scripts/README.md

Development scripts for Kubernetes documentation

Script	Description
find_pr.py	Find what GitHub pull requests touch a given file.
upstream_changes.py	Find what changes occurred between two versions.
test_examples.sh	This script tests whether a change affects example files bundled in the website.
check-headers-file.sh	This script checks the headers if you are in a production environment.
diff_l10n_branches.py	This script generates a report of outdated contents in content/<l10n-lang> directory by comparing two l10n team milestone branches.
hash-files.sh	This script emits as hash for the files listed in $@
linkchecker.py	This a link checker for Kubernetes documentation website.
lsync.sh	This script checks if the English version of a page has changed since a localized page has been committed.
replace-capture.sh	This script sets K8S_WEBSITE in your env to your docs website root or rely on this script to determine it automatically
check-ctrlcode.py	This script finds control-code(0x00-0x1f) in text files.

Requirements

Some of those scripts have external requirements. You can install them with the following commands:

python3 -m pip install -r requirements.txt

find_pr.py

$ ./find_pr.py --help
Usage: find_pr.py [OPTIONS] PATH

  Find what GitHub pull requests touch a given file.

  ex: ./find_pr.py --tags "language/fr" "content/fr/_index.html"

Options:
  --tags TEXT          Tags of PullRequest (Can be passed multiple times)
  --token TEXT         GitHub API token. (Default env variable GITHUB_TOKEN)
  --last-n-pr INTEGER  Last n-th PullRequests
  --help               Show this message and exit.

upstream_changes.py

$ ./upstream_changes.py --help
Usage: upstream_changes.py [OPTIONS] PATH

  Find what changes occurred between two versions

  ex: ./upstream_changes.py content/fr/_index.html

Options:
  --reference TEXT  Specify the reference version of the file. Default to the
                    English one.
  --git-path TEXT   Specify git path
  --help            Show this message and exit.

test_examples.sh

This script tests whether a change affects example files bundled in the website.

To install the dependencies:

$ ./scripts/test_examples.sh install

To run the examples:

$ ./scripts/test_examples.sh run

check-headers-file.sh

This script checks the headers if you are in a production environment.

./scripts/check-headers-file.sh

diff_l10n_branches.py

$ scripts/diff_l10n_branches.py --help
Usage: diff_l10n_branches.py [OPTIONS] L10N_LANG L_COMMIT R_COMMIT

  This script generates a report of outdated contents in `content/<l10n-
  lang>` directory by comparing two l10n team milestone branches.

  L10n team owners can open a GitHub issue with the report generated by this
  script when they start a new team milestone.

  ex: `scripts/diff_l10n_branches.py ko dev-1.15-ko.3 dev-1.15-ko.4`

Options:
  --src-lang TEXT  Source language
  --help           Show this message and exit.

hash-files.sh

This script emits as hash for the files listed in $@.

$ ./scripts/hash-files.sh

linkchecker.py

This a link checker for Kubernetes documentation website.

• We cover the following cases for the language you provide via -l, which defaults to 'en'.
• If the language specified is not English (en), we check if you are actually using the localized links. For example, if you specify zh as the language, and for link target /docs/foo/bar, we check if the English version exists AND if the Chinese version exists as well. A checking record is produced if the link can use the localized version.

Usage: linkchecker.py -h

Cases handled:

- [foo](#bar)                         : ignored currently
+ [foo](http://bar)                   : insecure links to external site
+ [foo](https://k8s.io/website/...)   : hardcoded site domain name

+ [foo](/<lang>/docs/bar/...)  : where <lang> is not 'en'
  + /<lang>/docs/bar           : contains shortcode, so ignore, or
  + /<lang>/docs/bar           : is a image link (ignore currently), or
  + /<lang>/docs/bar           : points to shared (non-localized) page, or
  + /<lang>/docs/bar.md        : exists for current lang, or
  + /<lang>/docs/bar/_index.md : exists for current lang, or
  + /<lang>/docs/bar/          : is a redirect entry, or
  + /<lang>/docs/bar           : is something we don't understand, then ERR

+ [foo](/docs/bar/...)
  + /docs/bar                : contains shortcode, so ignore, or
  + /docs/bar                : is a image link (ignore currently), or
  + /docs/bar                : points to a shared (non-localized) page, or
  + /docs/bar.md             : exists for current lang, or
  + /docs/bar/_index.md      : exists for current lang, or
  + /docs/bar                : is a redirect entry, or
  + /docs/bar                : is something we don't understand

lsync.sh

This script checks if the English version of some localized contents have changed since a localized version has been committed.

The following example checks a single file:

./scripts/lsync.sh content/zh/docs/concepts/_index.md

The following command checks a subdirectory:

./scripts/lsync.sh content/zh/docs/concepts/

check-ctrlcode.py

This script finds control-code(0x00-0x1f) in text files. It will display illegal character in browser.

Usage: ./check-ctrlcode.py <dir> <ext>

  <dir>    Specify the directory to check.
  <ext>    Specify the extension to check.

For example, we can execute as following.

  ./check-ctrlcode.py ../content/en/ .md

The output is following format.

  "{0} <L{1}:{2}:{3}>: {4}"

  {0} : The path of file that a control-code exists.
  {1} : The line number that a control-code exists.
  {2} : The column number that a control-code exists.
  {3} : The found control-code.
  {4} : The one-line strings in the file.