[Docs] Add link checker for docs

antonymilne commented 1 month ago

Description

Add a link checking step to the build of both vizro-ai and vizro-core docs on RTD. There's no good tool built into mkdocs for this, but https://github.com/linkchecker/linkchecker works quite well here and seems fast enough.

We now have three scripts that can be run in the docs environment:

# For local development, since it includes hot reloading:
hatch run docs:serve 
# Used to build docs on RTD but can also be done locally:
hatch run docs:build
hatch run docs:link-check

@stichbury I've fixed/ignored all the errors I found apart from this one, where I can't find an authoritative-looking link to the INCITS guidelines that actually works. Please can you suggest something?

URL        `https://standards.incits.org/apps/group_public/download.php/131246/eb-2021-00288-001-INCITS-Inclusive-Terminology-Guidelines.pdf'
Name       `INCITS Inclusive Terminology Guidelines'
Parent URL file:///home/docs/checkouts/readthedocs.org/user_builds/vizro/checkouts/475/vizro-core/site/pages/explanation/documentation-style-guide/index.html, line 2257, col 316
Real URL   https://incits.connectedcommunity.org/higherlogic/ws/public/download/131246/
Check time 0.605 seconds
Warning    [http-redirected] Redirected to
           `https://incits.connectedcommunity.org/higherlogic/ws/public/download/131246/'
           status: 301 Moved Permanently.
Result     Error: 404 Not Found

Screenshot

Notice

[x] I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":
- I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
- I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
- I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
- I have not referenced individuals, products or companies in any commits, directly or indirectly.
- I have not added data or restricted code in any commits, directly or indirectly.

stichbury commented 1 month ago

The INCITS link has gone! I found one on the NIST website https://nvlpubs.nist.gov/nistpubs/ir/2021/NIST.IR.8366.pdf but I think we'll follow Google as a more accessible standard.

stichbury commented 1 month ago

Added a commit with a link that works, to replace the one broken within the docs style guidelines.

mckinsey / vizro