pre-commit: ignore unreferenced Hyperlink targets

[absorb-it]

Ignore wrong reports about unreferenced Hyperlink targets - see also rstcheck/rstcheck#77

Sometimes it makes sense to have targets for future referencing included, but even used hyperlink targets are reported as errors. Without this change it is impossible to write or update any documentation - please change this.

[acolombier]

Could you provide an example of the issue this is fixing?

[absorb-it]

Could you provide an example of the issue this is fixing?

#825 or #824
see also #796 which has the same issue and some comments on the issue

[ronso0]

Without this change it is impossible to write or update any documentation

When I run into this I check if the current file is affected and if i can fix it.
If not, I use SKIP (one time ignore) and run SKIP=rstcheck [git command]. It can also be added to a global ignore list, but I don't rememer the command.

[ronso0]

IIUC all controller pages have a reference at the top so the page is listed in https://manual.mixxx.org/2.5/en/hardware/manuals.html ??
Maybe it's just that what's broken?

Sometimes it makes sense to have targets for future referencing included

We shouldn't add unused references. YAGNI : )
Add it when it's needed.

[ronso0]

Did you already check for an upstream report / fix?
https://github.com/rstcheck/rstcheck/

edit whoopsy, you did, I overlooked the first post

[absorb-it]

Without this change it is impossible to write or update any documentation

When I run into this I check if the current file is affected and if i can fix it. If not, I use SKIP (one time ignore) and run SKIP=rstcheck [git command]. It can also be added to a global ignore list, but I don't rememer the command.

seems like overkill to skip complete rstcheck, just to be able to upload and than collide with your pre-commit check again.

[absorb-it]

Sometimes it makes sense to have targets for future referencing included

We shouldn't add unused references. YAGNI : ) Add it when it's needed.

as said before: "even used hyperlink targets are reported as errors"

[absorb-it]

Did you already check for an upstream report / fix? https://github.com/rstcheck/rstcheck/

Ticket is already open rstcheck/rstcheck#77 but was closed because it's an upstream issue. Same happens with recent rstcheck 6.2.5.

[absorb-it]

Just to summarize: There are already "unreferenced hyperlink targets" in this documentation. The rstcheck for unreferenced hyperlink target fails for all hyperlink targets, not only for unreferenced ones.

With the current state it's impossible to commit changes on documentation rst files which contain hyperlinks or add new documentation rst files containing hyperlinks. The suggested fix will change this with the minimal impact. rstcheck is still used and will only ignore all existing and all upcoming hyperlink target checks.

[alajovic]

+1 on this. New contributor here. I wanted to document a small change I had made to a mapping and was stopped by this problem. It was quite confusing because it was giving the impression that I had made some kind of a mistake in my edit.
I think ignoring this error is an acceptable band-aid. A cleaner, proper solution may take time to manifest, and until it does, having a dysfunctional check serves no purpose. It's just causing lost time and frustration.