Add docs-check-links.yml and docs-check-links.sh files in .github/workflows

[slevis-lmwg]

Description of changes

Add github workflow to check whether links in the documentation still work.

Specific notes

Contributors other than yourself, if any:
@samsrabin

CTSM Issues Fixed (include github issue #):
Fixes #3218

Are answers expected to change (and if so in what way)?
No

Any User Interface Changes (namelist or namelist defaults changes)?
No

Does this create a need to change or add documentation? Did you do so?
?, no

Testing performed, if any:
None, yet

[slevis-lmwg]

@samsrabin I introduced these two files

docs-check-links.sh
docs-check-links.yml

using check-clm6-aliases as a template. I doubt that what I did works so far. When you have a chance:

• Could you confirm whether I'm on the right track?
• Could you point out things that I need to correct?
• Do I need to replace "http_code" with something like https:// or similar? What about $URL?

When I'm ready to test this, would I make a change to an .rst file in the documentation and push to the PR?

[samsrabin]

• Could you confirm whether I'm on the right track?

Yes!

• Could you point out things that I need to correct?

1. I think it would be best for your new "Check documentation links" job to be added to the docs.yml Workflow, which has a refined set of triggers.
2. GITHUB_TOKEN isn't actually used in the docs-check-links.sh script.

• Do I need to replace "http_code" with something like https:// or similar? What about $URL?

http_code no; that just tells curl to return the code (e.g. 200 for exists and accessible; 301 for permanently moved; 404 for not found).

$URL sort of. This command should be put inside a loop that loops through all the URLs found in the documentation:

for $URL in $list_of_found_urls; do
    link_code="$(curl -s -o /dev/null -w "%{http_code}" $URL)"
    # Add code to save bad links to one or more arrays
    ...
done

# Throw error or success message
...

I leave it to you to figure out how best to find all URLs.

When I'm ready to test this, would I make a change to an .rst file in the documentation and push to the PR?

The first thing to test will be that your docs-check-links.sh script works, which you can do locally or on an NCAR cluster. Once you know that's working, go ahead and push to this PR. I think, if you've moved your new job to docs.yml, it should trigger automatically. Make sure it fails. Then you'll need to fix all the broken links so that the test passes before we can merge.

[ekluzek]

This looks good to me. I can't see anything to comment on.

[ekluzek]

Ahh, @slevis-lmwg @samsrabin has some good comments above that would be good to bring in before merging. It would be good to have the docs workflows in one place.

As he said, I made some requests.

[samsrabin]

OH, actually: It looks like there should be a built-in Sphinx link checker! https://sphinx-intro-tutorial.readthedocs.io/en/latest/sphinx_extensions.html#linkcheck

But I think I'd need to update doc-builder for that.