Move linkcheck to a cronjob-style workflow

[cjolowicz]

The problem with running linkcheck within the Tests workflow is that a broken link will affect every PR, even when unrelated to docs.

Recent cases:

• pip.pypa.io: documentation restructured
• badgen.net: experiencing issues

There's also the issue of some links related to our own release not yet available when it's published.

A cronjob-workflow might also be a good idea for running tests with unpinned dependencies, or on the upcoming Python release.

[staticdev]

@cjolowicz I just saw this issue and was thinking about that. There are actually two cases:

1. Independent of PR link broke (eg. Poetry website went offline)

Then a CRONjob would be handy for docs workflow.

2. PR changes something in the documentation and can introduce a broken link

Then it also makes sense to run linkcheck.

Quickly checking triggers documentation I see there could be a condition for each case. Something like:

on:
  schedule:
    - cron:  '0 1 * * *'  # everyday at 1am
  push:
    paths:
      - '**.rst'
      - 'docs/**'  # this could be also used to run selectively docs-build?

I also like that you have a separate workflow on cookiecutter for docs. Maybe we could have the same on generated project?

[cjolowicz]

I like this idea!

Some thoughts/suggestions:

• We can work on a PR in the instance repository. That'll allow us to test the CI as well.
• The User Guide can be updated in a separate PR here, after the instance PR is merged.
• It would be great if we could avoid duplicating the Nox session. It could be a wrapper session using session.notify on the docs-build session with the linkcheck option in posargs.
• IIUC your example does not run for PRs from forks? That should be changed then.
• Would it be possible to make this part of the existing Tests workflow, and check the paths in the step running Nox? We could still have a cronjob on main, in a separate workflow. update: Looks like that's not easily possible.
• Once per week is probably enough for the cronjob.

[cjolowicz]

Worth noting that broken links in docstrings would only be detected by the cronjob. But I'd rather have that than every Dependabot PR failing because some link wasn't reachable.

As for docs-build, is it a good idea to use the paths filter here as well? I think it's maybe better not to do that, because some projects have most of their documentation in docstrings. (We'd still have the Flake8 checks though. And the Read the Docs PR build but only if the user configured that.)

[staticdev]

@cjolowicz I am still not sure about the best overall solution. My idea was to add linkcheck to normal docs-build and run in a separate workflow (like in the PR above).

The idea of using paths filter on docs-build is basically to avoid that Dependabot PRs get broken. Also, if someone make a PR that does not change any RST file or docs folder, I don't see a reason to build the documentation.

About the flake8 checks.. I am not sure. To follow the same train of though, I would compartmentalize and find a way to only run this specific checks on docs workflow. No strong opinion, maybe we should experiment and see in real life how practical are the approaches and adapt if we find more problems.