Draft script to find diverging links

[Carreau]

See Quansight-Labs/czi-scientific-python-mgmt#88

Incomplete, in particular we should handle relative and anchor linsks, starting with #, and .

$ python tools/divergent_links.py docs/_build/html

[github-actions]

Coverage report

This PR does not seem to contain any modification to coverable code.

[Carreau]

Not perfect, but in a usable state

[Carreau]

As a note from yesterday's meeting,

This just prints group of diverging link:

• content of the a tag, href, and which page ti was found on.

As there are too many valid reasons to have diverging links, it does not fail, and is not in CI.

Reasons for diverging links are for example: next, previous, view on github ...

[gabalafou]

This is a nice tool. Should we add some instructions in our docs so that theme adopters can also use it?

I have a few review questions and comments, could you look into those?

My biggest overall question though is whether we need to look for links with same name but different URLs across pages (versus evaluating a single page at a time for such links). In the case of same name-different URL links, the issue is most pressing when such links occur on a single page. It puts up a barrier for someone who uses speech commands (like "go to [link name]"). Imagine you have a long article that mentions various APIs and the word "API" gets linked to two different pages. Then when the user says "go to API", the speech command software has to pull up a secondary menu so that the user can clarify which URL they actually want to go to. But this is much less of a problem for such links that occur on different pages.

PS. While it is true that one of the WCAG criteria is for UI elements that are repeated across pages on the site to be consistently labeled, that's a bit of a different concern than the one I raised. In that case, it's like, if you have a "contact us" link in the same place across all the pages on your site, then it should NOT say "contact us" on one page but then "send us feedback" on another.

[gabalafou]

My terminology was terrible (divergent versus convergent) but you got my definition backwards. A divergent link is same name, different URLs.

So this got me a bit confused when I reviewed the PR.

I think the code in this PR actually detects divergent links (same name, different URLs), in which case the comment is wrong.

[gabalafou]

PS. Please let's ditch my terminology. It's terrible. Nobody is going to be able to remember which side of divergent or convergent they are on. We should probably stick with names like same-name-different-URL links and same-URL-different-name links, unless we can think of something creative and memorable.

[gabalafou]

Or maybe, less of a mouthful... name-consistent links (same name, different URLs) versus name-inconsistent links (different names, same URL)

[gabalafou]

But I don't like that either because it makes it sound like one is bad (inconsistent) and the other good (consistent) whereas neither of them are good. So maybe, URL-inconsistent links versus name-inconsistent links.

[Carreau]

I've reworded.

[Carreau]

I don't think we need this script to be perfect, as mentioned in the title of the PR this is mostly a draft script as it is not part of CI, so I think we should not strive for perfection, but something that works and we can refine, until we are at a state were we are both happy with the content of the docs and the output/content of the script. Otherwise we'll spend an eternity tweaking that with enomous changes instead of progressive updates that are easier to review.

[Carreau]

I added also a --all options so that one can check each page independently or all the pages at once.

[gabalafou]

Thanks for updating @Carreau.

My one concern right now is that if we merge this PR to the repo, we will essentially be committing orphaned code. The code added in this PR isn't called anywhere else. It's not referenced in the docs. It's not exactly clear how it is intended to be used.

I don't really know what we do next with this. Do we add it to one of the Sphinx built-time hooks? Do we add a sentence or two about the tool in the accessibility section of the docs?

[gabalafou]

We chatted about this in the October 3 czi sci py team sync and outlined some next steps:

1. Use the script on the PST docs
2. If useful, add it as a CI job to PST
3. Further down the road, if it proves to be useful for us, we can think about ways to make it useful for theme adopters

[drammock]

My one concern right now is that if we merge this PR to the repo, we will essentially be committing orphaned code. The code added in this PR isn't called anywhere else. It's not referenced in the docs. It's not exactly clear how it is intended to be used.

FWIW other repos I work on have a tools/ folder at the repo root, full of things just like this (scripts that are useful for maintainers, not really part of the package, excluded from the MANIFEST, etc). So I don't see that as inherently problematic. That said, the functionality added here could be of general interest / utility for theme users. So long term I'd aim to either (1) add it to the public API of the theme (e.g., from pydata_sphinx_theme import check_link_consistency) or (2) make it a small separate package and host it in the scientific-python organization.

[gabalafou]

Thanks for those thoughts @drammock

[Carreau]

The goal is to have it run in CI and refine. int just that right now there are more diverging links that needs to be updated. My hope is that with this merged, every few days someone can send and update to the script and docs, until it runs without divergences.

Then we can start to think about packaging it and making it stable/configurable. Otherwise I can keep pushing on this PR, but that means I have to find the time to fix everything ; and I would prefer to get user feedback on the Usage .

[drammock]

just one clarification. +1 for merge

[drammock]

Ok let's try it out!