Add a scheduled `linkcheck` workflow

[purva-thakre]

Will add better details later.

• have linkcheck ignore all doi/arxiv links

---

Previous issue description

• In .github/workflows, add a workflow that will run on a schedule (frequency could be daily at midnight or on a weekly basis, TBD). Currently, make linkcheck is run due to the triggers shown below in .github/workflows/build.yml

https://github.com/unitaryfund/mitiq/blob/35139fe291cc7c37e9d062a60c7a2079e0416e00/.github/workflows/build.yml#L3-L14

As the triggers for make linkcheck will be different, it might be better to define a separate workflow labeled .github/workflows/linkcheck.yml

• make linkcheck tends to fail due to a 403 related to IOPScience links in docs/source/refs.bib. Replace the IOPScience links with those allowed by arxiv. See https://github.com/unitaryfund/mitiq/pull/2277#issuecomment-2048129304 for more info.

• linkcheck ignores some links in docs/source/conf.py because those would cause the job related to make linkcheck fail. Remove the ignored links from docs/source/conf.py and replace the IOPScience links with arxiv links. Then, use a redirect pattern as discussed in https://github.com/unitaryfund/mitiq/pull/2277#issuecomment-2048165904

[natestemen]

So ultimately the reason we use the link checker is to validate that links in our documentation are not dead (bad UX). This is most important when doing a release since a new version of the docs will be deployed to mitiq.readthedocs.io/en/stable. What if we only ran linkcheck on the PR that generates the release (i.e. the thing that comes right before a new version of the docs is shipped)?

This could be achieved by having a label (say release) which we use to label such a PR and then add an action that only runs when pull requests are labeled with such a tag. See further details here: https://stackoverflow.com/questions/62325286/run-github-actions-when-pull-requests-have-a-specific-label

One downside to this is that maintainers have to remember to add this label in order for linkcheck to run. If we went this way it would be documented, but it wouldn't happen automatically.

Alternatively, I do like the idea of running linkcheck weekly. Only downside I can think of there is that it is no ones "responsibility" when it fails. Someone has to "claim it", instead of it (annoyingly) disrupting your PR and requiring you to fix it.

[purva-thakre]

Only downside I can think of there is that it is no ones "responsibility" when it fails. Someone has to "claim it",

In case of a failure, the milestone manager uses a randomizer to assign it to someone?

[natestemen]

Or maybe it makes sense to add this to the responsibility list of the milestone manager.

[cosenal]

We can run linkcheck on every PR, but only make it fail the build on the PR release, I like that idea, Nate! cc @FarLab as the current milestone manager 😬

We should still do the other actions that @purva-thakre mentioned about specific links, such as, redirecting arxiv.org links to export.arxiv.org.

[purva-thakre]

Found a Sphinx extension to redirect the arxiv links: https://documatt.com/sphinx-reredirects/usage.html

Linkcheck also has an option for allowed redirects: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_allowed_redirects

Edit: I am not too familiar with the release process for Mitiq. Going through the release notes, it says that a new tag is created for the release. I wonder if we could setup the workflow to be triggered when a new version tag is created?

If we use something like a release branch, the workflow could be triggered when a new release branch is created as well. https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#example-including-branches-and-tags

[nathanshammah]

Thanks @purva-thakre for opening this issue. I am in favor of a change of the status quo, i.e., a high percentage of failed checks in docs CI come just from linkcheck-related DOI validation.

A step back: I think that linkcheck is mostly useful to check that links to things like internal Mitiq documentation pages or other docs are properly linked. Most of our external links are DOI or other links like arXiv that will likely stay the same "forever". A way to limit linkcheck domain to the documentation in my opinion would be fine. What about skipping the references file in the docs (there is an option,--skip-file)? And this way we also remove the conf.py list of exceptions. It may need some tidy up elsewhere to make sure the links to papers only occur in the references, but this should solve most current fails.

[purva-thakre]

Most of our external links are DOI or other links like arXiv that will likely stay the same "forever". A way to limit linkcheck domain to the documentation in my opinion would be fine. What about skipping the references file in the docs

Fine by me. There is indeed an option for skipping files. In this case, it would mean skipping everything related to refs.bib. If a docstring cites a reference from the bib file, it will require some additional tidying up, as you suggest.

https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_exclude_documents

@natestemen @cosenal Agree/Disagree with Nathan's suggestions?

Edit: Do we still want a weekly workflow or the one that gets triggered when a new release tag is created?

[natestemen]

I like the idea of skipping arxiv, and doi.org and other journal related links! It is their job after all to provide permanent links/redirects. We should trust them with that job. This can be achieved using a few regex's in the linkcheck_ignore list. Perhaps something like the following can replace our existing list.

linkcheck_ignore = [
    r"https://doi.org/.+",
    r"https://arxiv.org/.+",
    r"https://link.aps.org/doi/.+",
]

A step back: I think that linkcheck is mostly useful to check that links to things like internal Mitiq documentation pages

So make docs is enough to catch errors introduced in local file references. make linkcheck is not needed to catch the following situation:

1. add [link](./doesntexist.md) anywhere to the docs
2. run make docs
3. get the following error

   /mitiq/docs/source/guide/pec-3-options.md:347: WARNING: 'myst' cross-reference target not found: './doesntexist.md' [myst.xref_missing]

[purva-thakre]

I'll edit the issue description to have linkcheck ignore all DOI, arxiv links etc.

We still need make linkcheck for the things that are an inline link [some_text](external web page).

For example, our contributing guide has most of those, I think.

https://github.com/unitaryfund/mitiq/actions/runs/8648542706/job/23712587752#step:7:746 https://mitiq.readthedocs.io/en/stable/contributing.html