checker

README

Docs Link Checker

Overview

Checker is designed to quickly check hyperlinks, :ref: directives, and :doc: directives to ensure they are valid. Based on Nathan Leniz's tool of the same name, this fork improves performance, adds the ability to exclude specific URLS, and changes the default values.

Install

go install github.com/MongoCaleb/checker@latest

Use

There are several ways to use checker.

1. Run it against the entire docset. With multithreading and reasonable internet connectivity, this process takes a matter of seconds. To do this, simply navigate to the root directory of your docs repo and run checker.

2. Check a specific file or files by using the --changes flag. Multiple files are comma-delimited with no spaces:

checker --changes /examples/foo.yaml,/source/bar.txt

1. Check files that have changed in the current diff. This can be accomplished with:

git diff --name-only | tr "\n" "," | xargs checker  --changes

NOTE: To check recent files, be sure to run this before adding the files to the current commit (before running git add.)

See the --help flag for more info.

checker --help

Excluding links

There are times when you may want to not check URLs. For example, if your docset has examples that use fake URLs, you want to make sure those URLs are ignored. One common example is to exclude checking http://example.com URLs.

To exclude URLS, create the following file: ./config/link_checker_bypass_list.json

In this file, add the URLs to be excluded and the reason for the exclusion in the following format:

[
    {
        "exclude":"example.com",
        "reason":"is not real url"
    },
    {
        "exclude":"api/client/v2.0",
        "reason":"will always return 400"
    }
]

Running as a Github Action.

TBD. See https://github.com/actions/setup-go.

What it does

Specifically, it checks to ensure all links are valid. It does this in the following ways:

• It will find all raw links and check them (https?...).
• It will find all role uses defined in the latest release version of rstspec.toml and check resulting interpreted urls.
• It will optionally check uses of :doc: and :ref: targets. Note: checker DOES NOT ignore rst comments. Use the optional -d and -r flags to check for :doc: and :ref: targets, respectively.

Documentation

Overview

Copyright © 2021 Nathan Leniz <terakilobyte@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.