linkcheck option to ignore certain protocols

[72757373656c6c]

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

Run:

sphinx-build -b linkcheck source/ _build/linkcheck

Produces an error for each man:, for example:

( commands: line   18) broken    man:bash(1) -

conf.py has:

manpages_url = "man:{path}"

Markdown example:

{manpage}`bash(1)` - GNU Bourne-Again SHell

HTML output:

man:bash(1)

Firefox browser has an application content type of man (x-scheme-handler/man), which is handled by an xdg desktop file to convert a local man page to html and display it in the browser.

Describe the solution you'd like

An option added to sphinx-build -b linkcheck source/ _build/linkcheck to ignore specified protocols, like manpage url.

Current options for the linkcheck builder.

Describe alternatives you've considered

An alternative is to pipe the output to grep and filter out man: errors.

[jayaddison]

Thanks for the feature request / bugreport!

Do you expect to ignore additional URI schemes other than man: when using this? The reason I ask is that it would be fairly straightforward to add that scheme to the ignore-list alongside mailto: and tel: in the codebase.

I'll also note that man: doesn't appear to be a registered (or provisional) IANA URI scheme at the moment - but if it's supported by Firefox (and/or other browsers?) perhaps it's worth considering anyway.

[AA-Turner]

Would it make sense to just whitelist http and https? I'm not sure what other schemes we could reasonably expect to work...

A

[AA-Turner]

Checking non-http was introduced in #7985 (#5208), it seems to support rST with just anchors (`2D <#2d-image>`__)

[72757373656c6c]

This conf.py option works:

linkcheck_ignore = [ r'^man:.+' ]

But it generates a message per link:

 ( commands: line   18) -ignored- man:bash(1)

Maybe an option without the messages:

linkcheck_ignore_protocol = [ 'man', 'info', 'help', ] 

I first came across this many years ago in KDE's Konqueror documentation - Viewing Help, Man and Info Pages, but it also works in Firefox. I don't have a link for that, but this might help explain that a protocol handler can be added. Google-Chrome used xdg-open, so it works there too.

href The URL that the hyperlink points to. Links are not restricted to HTTP-based URLs — they can use any URL scheme supported by browsers: