Run make linkcheck on only changed files

[laysauchoa]

Running make linkcheck for all the files is slow and not necessary if the files did not changed.

Describe the solution you'd like
I wonder if there is any possible way to run make linkcheck on specific files or files that have changed. Seems like the only way to run is running in all the files.

Describe alternatives you've considered
This tool could be useful but is no longer working as explained:
wpilibsuite/sphinxext-linkcheckdiff#6

Additional context
Pretty much want to be able to run the command in specific files rather than the whole project. Having the checked links cached could be an option. I could not find anything else related.

Are there any alternatives out there for this?

[francoisfreitag]

Hi @laysauchoa,

Running make linkcheck for all the files is slow and not necessary if the files did not changed.

Are you thinking of local files?
linkcheck is also to verify links to sites served over the network, which change on their own. The most common example is probably a web page being taken down without redirects, so a user following this link ends up with a response 404 Not Found. Even if your documents don’t change, the link may become invalid.

[AA-Turner]

Closing for @francoisfreitag's reason--a link can die at any time, so checking the entire documentation is the proper thing to do here.

A

[lornajane]

I understand why it seems like we are doing it wrong, but our use case (I work with @laysauchoa ) is that we have a busy open-source docs platform, and a broken link causes every PR build to fail until either the third party site comes back up, or the main branch is fixed and every PR is rebased. We'd like to run regular (probably daily) link checks over all the hundreds of pages, but for incoming docs changes it would be useful to be able to only check the changed content. Right now we have a lot of infrequent contributors, all thinking they have done something wrong because the builds fail.

One possibility is that we disable link checking altogether, and instead fix anything that gets flagged by the daily build. A better option would be to check new links as they are added, and use a regular check to ensure the continued health of the entire documentation - so that's our request.

We're happy to try to make this contribution ourselves if you think it's even possible, and maybe could offer some guidance on whether it seems plausible (I'm not familiar with the internals, I wouldn't be too surprised if this was impossible for some reason and we should consider a different tool). And if so, perhaps you would consider re-opening this so we can discuss along the way.

[tk0miya]

You can specify source filenames as arguments of sphinx-build command.

sphinx-build -b linkcheck srcdir outdir path/to/target1.rst path/to/target2.rst ...

Sidenote: The arguments do not reduce the reading processing. So all documents in the project will be read and processed once. But the linkcheck-ing process will go only for the specified files.

[laysauchoa]

Thanks @lornajane for bringing this up and thanks a lot @tk0miya for showing this command. It works for my use case 👍