search

canonical / sphinx-docs-starter-pack

A documentation starter-pack
https://canonical-starter-pack.readthedocs-hosted.com/
Other
15 stars 38 forks source link

fix: manpage url linkcheck failures #226

Closed dviererbe closed 5 months ago

dviererbe commented 5 months ago

The Ubuntu manpage urls return a "404 Not Found" error, because when verified by linkcheck the JavaScript code that will look up the searched manpage at runtime does not get executed.

To solve this error we staticaly define the URL that would otherwise be looked up at runtime. Therefore we use dist-info to look up the latest Ubuntu distribution.

One drawback is that the documentation has to periodically be regenerated, because a newer Ubuntu distribution will be released every 6 months.

Bug: #224

dviererbe commented 5 months ago

note: force-pushed to remove an unwanted change that I accidentally committed.

dviererbe commented 5 months ago

note: RTD fails because /bin/sh: 1: distro-info: not found. We need to install the distro-info package to fix this. I thought that it may be installed by default.

dviererbe commented 5 months ago

note: force-pushed to fix typo in .readthedocs.yaml

dviererbe commented 5 months ago

note: force-pushed, because I noticed that my local repo was outdated and moved the manpage stuff to conf.py with a setting in custom_conf.py to overwrite if desired.

dviererbe commented 5 months ago

@ru-fu This PR is now ready for review.

ru-fu commented 5 months ago

One drawback is that the documentation has to periodically be regenerated, because a newer Ubuntu distribution will be released every 6 months.

I don't think that's a drawback - the link check will only run for updates anyway, and if there are no updates within 6 months, I wouldn't want to just assume that the new links will be valid but wait for an update. ;)

Also, we specify which distro to use in the .readthedocs.yaml file, so it won't automatically update.

AnneCYH commented 3 months ago

Capturing this here for completeness sake.

Suggested a potential workaround to use the "latest" word in the URL (since it seems to redirect to the latest manpages) to avoid having to keep manually updating and pointing to the latest Ubuntu version. For example, use "https://manpages.ubuntu.com/manpages/latest/en/man8/dkms.8.html" instead of "https://manpages.ubuntu.com/manpages/noble/en/man8/dkms.8.html".

But as confirmed by @dviererbe unfortunately the redirect only works with Javascript that has to be interpreted by the client, and that can't be done with linkcheck.