Implement a configuration variable that controls linkcheck verbosity

[namurphy]

Is your feature request related to a problem? Please describe.

When using make linkcheck, a line is printed for each link that gets checked. This includes broken links, redirects, and working links. One of the pain points of using make linkcheck is scrolling through thousands of links to find only a handful of broken links. The large amount of output for big projects also makes it harder to scroll up to previous commands in a terminal.

Describe the solution you'd like

It would be helpful to have a configuration variable that controls the verbosity of the output when using linkcheck. This configuration variable could be set such that the working links don't get printed to standard output.

Describe alternatives you've considered

• Only include broken links & redirects in standard output and skip printing working links. This would personally be my first choice, but it would change the default behavior. Also, there may be use cases where printing out the commands is useful (i.e., to make sure that the command is still working and didn't get stuck somewhere).
• Repeat printing the broken links at the end (Publish linkcheck failures at end of test #8791). This would address the bulk of the issues, though it would still be difficult to scroll up to previous commands in a terminal. Having a configuration option would provide more control by users. It'd be possible to have the suggestion in Publish linkcheck failures at end of test #8791 be the default behavior, and simultaneously implement a configuration variable.
• Keep the status quo. There are workarounds for this. For example, I could redirect the output into linkcheck.txt, and then do grep -v " ok " linkcheck.txt or use other Sphinx flags. Workarounds like this might complicate the workflow, require intermediate knowledge of Unix or Sphinx, and/or take longer to figure out how to set them up than it would to use a configuration variable.
• Describe a preferred workaround in the linkcheck documentation. This would have saved me time trying to figure this out, but it would still be less user-friendly than a configuration option.

Thank you!

[mgeier]

I don't have a strong opinion on this, but I wanted to mention that the linkcheck builder already generates two files:

• output.txt, which contains only entries for redirected and broken links
• output.json, which contains all entries, but should be easily machine-readable

[namurphy]

That is indeed helpful! I didn't notice them since they showed up in a subdirectory (i.e. _build/linkcheck/). Would it be worth mentioning those files in the linkcheck documentation?

Also — my sincere thanks to everyone who contributed the link checking capabilities! We've been finding it to be incredibly helpful.

[AA-Turner]

cc @jayaddison

[jayaddison]

@namurphy if you're on a relatively recent version of sphinx: does the --quiet option achieve more-or-less what you want here?

It can be supplied via the makefile like this:

$ make linkcheck SPHINXOPTS="--quiet"

Edit: link fixup

[namurphy]

Thank you for the reply! Running that command gave me:

$ make linkcheck SPHINXOPTS="--quiet"
usage: __main__.py [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
__main__.py: error: unrecognized arguments: --quiet
make: *** [Makefile:20: linkcheck] Error 2

Edited to add: Removing the -- in --quiet got the command to run. It ran but I got:

WARNING: file '.../docs/quiet' given on command line does not exist, 

The only links checked appeared to be from the index file. So I don't think removing the -- worked.

This was with Sphinx 7.2.6.

[jayaddison]

Ok, thanks @namurphy - handling of the SPHINXOPTS setting in the makefiles has changed a few times; I think the alternative below should work with v7.2.6 :

$ SPHINXOPTS="--quiet" make linkcheck

(roughly speaking: what that runs, Sphinx should emit one warning for each linkcheck failure, and very little other output)

[AA-Turner]

It may need to be -q, the long options haven't yet been released in Sphinx (#11776).

A

[namurphy]

Alas, still no luck. Running the commands with either -q or --quiet still led to the links being printed out.

I'm wondering if there's something specific about the configuration for the project I'm testing this on (PlasmaPy). Have you tried these commands on another project? In the meantime I'm going to try updating our Makefile to what sphinx-quickstart now provides (which is probably worth doing anyway).

Thank you again!

[jayaddison]

Thanks @namurphy @AA-Turner - yep, my mistake, that should have been -q, and yes indeed, the format of the Makefile -- and in fact perhaps the variant of the make program (BSD/GNU) may also be relevant.

@namurphy I'll check out a local copy of PlasmaPy to investigate this in a bit more detail.

[jayaddison]

I'm wondering if there's something specific about the configuration for the project I'm testing this on (PlasmaPy).

@namurphy ok, yep - in short, for the PlasmaPy Makefile:

• Before your quickstart template update, make linkcheck SPHINXOPTS="-q" would have enabled quiet mode.
• After the quickstart update, environment variables can additionally be read by make, so SPHINXOPTS="-q" make linkcheck would also work.

Have you tried these commands on another project?

Yep, I've enabled quiet mode while locally linkchecking a few projects, and in my opinion the output that it produces is relatively concise, while including most of the important details (source file, line number) -- essentially, it matches your first alternative description:

Only include broken links & redirects in standard output and skip printing working links. This would personally be my first choice, but it would change the default behavior. Also, there may be use cases where printing out the commands is useful (i.e., to make sure that the command is still working and didn't get stuck somewhere).

[namurphy]

@jayaddison — This is awesome! Thank you so much! I was able to get SPHINXOPTS="-q" make linkcheck to work with the most recent version of Sphinx after I updated Makefile to be closer to what sphinx-quickstart now provides.

To fully close this issue, perhaps we could mention this information in the linkcheck documentation (like something sort of like Changed in version 7.x: The -q and --quiet command line options can now be used to limit the verbosity of linkcheck output.). That way, someone doing a search for "linkcheck quiet" or "linkcheck verbosity" would be able to find this.

[AA-Turner]

@namurphy -- would you be open to opening such a PR to update the documentation?

A