NAME

repomatic broken-links - Check links, and manage the broken links issue

SYNOPSIS

repomatic broken-links [OPTIONS]

DESCRIPTION

Check the documentation links, and manage the broken links issue.

Crawls the documentation files with lychee, then combines its report with the Sphinx linkcheck output into a single "Broken links" issue. Creates or updates the issue when a checker found broken links, and closes it when every checker that ran completed clean. A checker that did not complete leaves the issue as it is. So does a run where no checker ran. The repository name selects the labels the issue carries.

Requires the gh CLI to be authenticated. lychee reads $GITHUB_TOKEN to lift GitHub's rate limit on the links it checks there.

In GitHub Actions, most options are auto-detected:
- --repo-name defaults to $GITHUB_REPOSITORY name component.
- --output-json defaults to ./docs/_linkcheck/output.json if it exists.
- --source-url is composed from $GITHUB_SERVER_URL, $GITHUB_REPOSITORY,


  and $GITHUB_SHA when --output-json is set.

OPTIONS

--lychee / --no-lychee

Crawl the documentation files with lychee, as `repomatic run lychee` does. Skipped when the repository holds none. A crawl that does not complete leaves the issue as it is.

--output-json FILE

Path to Sphinx linkcheck output.json file.

--source-url TEXT

Base URL for linking filenames and line numbers in the Sphinx report. Example: https://github.com/owner/repo/blob/<sha>/docs

--repo-name TEXT

Repository name. Defaults to the name component of $GITHUB_REPOSITORY.

--help / -h

Show this message and exit.

ENVIRONMENT

BROKEN_LINKS_LYCHEE

Crawl the documentation files with lychee, as `repomatic run lychee` does. Skipped when the repository holds none. A crawl that does not complete leaves the issue as it is.

BROKEN_LINKS_OUTPUT_JSON

Path to Sphinx linkcheck output.json file.

BROKEN_LINKS_SOURCE_URL

Base URL for linking filenames and line numbers in the Sphinx report. Example: https://github.com/owner/repo/blob/<sha>/docs

BROKEN_LINKS_REPO_NAME

Repository name. Defaults to the name component of $GITHUB_REPOSITORY.

BROKEN_LINKS__CLICK_DEFAULT_HELP

Show this message and exit.

EXIT STATUS

0

Success.

1

A runtime error, an aborted prompt (Ctrl-D), or a declined confirmation.

2

A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.

130

Interrupted with Ctrl-C: the process ends by SIGINT, reported as 130.

EXAMPLES

In GitHub Actions, with every default auto-detected

repomatic broken\-links

Report the Sphinx linkcheck output alone

repomatic broken\-links \-\-no\-lychee \-\-repo\-name "my\-repo"

AUTHORS

Kevin Deldycke