search

napari / docs

Documentation for napari (other than API docs)
BSD 3-Clause "New" or "Revised" License
10 stars 36 forks source link

Add broken link check to CI for documentation builds #439

Open GenevieveBuckley opened 3 years ago

GenevieveBuckley commented 3 years ago

📚 Documentation

cc @kne42

Proposal: add a linkchecker step to our CI for documentation builds. The docs build should fail if it finds broken links.

I think this python package would do the job well, it's super simple to use: https://github.com/linkchecker/linkchecker

Reason for change: there are five broken links right now on the napari.org main page alone. Lots more on other pages too. (Often we see this because the structure of the napari repo has changed, or a file is renamed slightly. There's less evidence of link rot from external sites we point to.)

sofroniewn commented 3 years ago

Wow that would be great! I was not familiar with that package, but it looks nice. I'm supportive, I know broken links have been a big issue in the past too

laysauchoa commented 2 years ago

Would love to contribute. Can I give a try to add the integration in this Issue?

Czaki commented 2 years ago

Would love to contribute. Can I give a try to add the integration in this Issue?

Feel free to try. Feel free to call me for a review.

laysauchoa commented 2 years ago

@Czaki I've some questions. Here I implemented in my forked version and I found out two things:

Czaki commented 2 years ago

Takes 8 min to run. so do you wanna to run this in every pull request or periodically?

As I fast check, the run that does not verify external links is much faster, and even now, it finds four dead internal links (and in the past will find much more). As we do not like to have a failure of test in PR because of reasons not related to PR I personally prefer to run internal docs links check in PR and external (global) links check run as a periodical job on the main branch (something like pre-release tests).

Lots of broken links. Some of the links we can fix the anchor, some of the links are actually invalid

For links like https://github.com/napari/napari/ i will ommit it using --ignore-url as github limits requests (or maybe even exclude more github checks)

many of the links leading to napari.org should be changed on relative links.

some of the links we can not fix the format but are working

could you give an example?

I am not sure how to handle the links that are currently not reachable

Some of the links that I check (ex vispy one) require visiting their website to find a new link or, even better switching to intesphinx if possible.

But the minimum job that should be done is to fix these four dead internal links and fix internal links that point to napari.org. But if you have a problem with any link please post it and someone will determine which link should be in this place.

Czaki commented 2 years ago

@alisterburt tool from this issue should be used before the release of 0.4.17 and all links fixed.

alisterburt commented 2 years ago

thanks for the ping @Czaki - I agree. @laysauchoa would you like to open up a PR where we can start to fix broken links and decide on when to run the check? 🙂

laysauchoa commented 2 years ago

Hi, yes: https://github.com/napari/napari/pull/5008

I think 8min is quite a long time to wait for every build. It could also be confusing to have to fix a random link in a file that you did not changed just because it is broken somehow. So my proposal would be something like this:

Of course, this is just a proposal and I'm happy to read your thoughts on that! Also, happy to do the changes accordingly.

I guess first step is to fix all the broken links :)

andy-sweet commented 2 years ago

I changed the milestone on this issue since I think introducing the broken link checker for v0.4.17 looks potentially challenging. But I left the milestone on napari/napari#5008 in case that turns into a PR where we fix the broken links and maybe add the checker in a disabled-by-default state.

Czaki commented 2 years ago

reopen as finally not completed and check is not enabled