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 |



## 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/