networkupstools / nut

The Network UPS Tools repository. UPS management protocol Informational RFC 9271 published by IETF at https://www.rfc-editor.org/info/rfc9271 Please star NUT on GitHub, this helps with sponsorships!
https://networkupstools.org/
Other
2.08k stars 350 forks source link

CI: Check asciidoc link/linkdoc/... validity during builds #1958

Open jimklimov opened 1 year ago

jimklimov commented 1 year ago

As confirmed during issue #1957 investigation, we can generate documentation entries intended to be cross-linked (within the present set of documents) with such links leading nowhere in fact, e.g. if some anchors were planned but forgotten, lost in refactoring, mis-typed or with wrong markup so not recognized, etc.

This issue is about somehow (using asciidoc itself? parsing the HTMLs/PDFs?) determining that documentation links which should lead to targets in the same codebase (not absolute URLs) in fact lead nowhere, and making it a fatal problem for automated builds eventually.

Feels related to #823 (fightwarn in C/C++ code) :)

For examples currently online, a generated wrong link for "A.2.2 ups: General unit information -> ups.status -> OL" looks like this:

For comparison, a nearby link to "NUT daisychain support notes" looks like this:

jimklimov commented 1 year ago

When it gets to this, also check if nut-website handles these links somehow differently compared to "local HTML" documentation builds. Maybe the solution would need to cater to many situations.

jimklimov commented 1 year ago

FWIW, it may make sense to adopt somehow the auto-URI scheme which includes the original filename, and makes some things easier, maybe. Looking at URLs like https://git-scm.com/docs/pretty-formats#Documentation/pretty-formats.txt-emnem as inspiration for this part of the idea.

jimklimov commented 3 months ago

Related to https://github.com/networkupstools/nut-website/issues/52 and (partially?) addressed by https://github.com/networkupstools/nut-website/pull/53 and https://github.com/networkupstools/nut-website/pull/54 introducing htmlproofer check ability into NUT-Website builds.

At the moment the subject is left "as is". Some issues were found and fixed, others await their time, and it does not seem like something for NUT CI to pick up soon, as the check takes tens of minutes (maybe a bit less if not crawling external dead links, but only cross-page references).