180 lines
6.4 KiB
Markdown
180 lines
6.4 KiB
Markdown
# 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.
|
|
``` |