Check all links in docs and make them more accessible

[stichbury]

Guidelines for links are as follows:

• We should comply with https://vizro.readthedocs.io/en/stable/pages/development/documentation-style-guide/#language
• Links should always work.

Task (1) Fix all links

Before we have perfection, we need to run through all the docs pages and fix issues like this one https://github.com/mckinsey/vizro/pull/422#discussion_r1566440210 where they arise.

Task (2) Set up style checking for future content

One way to enforce this ongoing would be to use Vale. I've asked how to do this: https://github.com/errata-ai/vale/discussions/807

Task (3) Add external link checking (if not already running) to CI.

We already have this for internal links in that we build with --strict but need to have something check links to Dash etc as Kedro does.

This ticket doesn't need technical writing skills nor does it need Vale knowledge. Good first issue for a new contributor!

[kaestro]

Hello, I'm interested in this and wonder if I may.

If I'm to be allowed, I have some questions on working on the issue

1. Does the 'Docs' mean all of the markdown files inside the vizro-core/docs/pages?
2. For those internal cross-referencing links, should is it only needed for me to check whether the links that are already put in but not working, are they the only of concern? Or should I make links to those that doesn't have links yet?
3. I have hard time understanding what 3rd condition means. What do you mean by links to Dash etc? Do you mean link needs to be heading towards etc page when couldn't find appropriate one?

[stichbury]

Hi @kaestro That would be fantastic, thank you for offering a contribution. Here are a few answers:

1. Yes, it's the markdown under vizro-core/pages/ and likewise the vizro-ai/pages docs, although they are a much smaller set. It would be wonderful if you could run through those pages and look at the descriptive text for links so they read well and are useful as per the style guide: https://vizro.readthedocs.io/en/stable/pages/development/documentation-style-guide/#links

2. To answer your question, the internal links are all OK because we use a --strict flag on our build tool and detect them at build time. So there's nothing to check with those.

3. Task 3 is to make sure that all links out to other docs (absolute links rather than relative links within the docs) are working. It's annoying when they break but we should catch them as part of our CI and fix them. Kedro use Sphinx to build their docs and use the linkcheck flag, but we use a different docs tool, so need to investigate if MkDocs have a similar option. I think they probably do, and if so, we just need to configure it.

If you prefer to focus just on Task 1, that would be wonderful, and the other two tasks can wait, or you can tackle all. Up to you! It's wonderful that you've offered to contribute.

[kaestro]

@stichbury

Thank you for all the replies and welcome. It helped a lot

I'll try to catch up on the Task 1 first.

If you don't mind, for it's my first time trying to contribute on open-source, I might take some time to start on working itself. It's because I've only used github as contributor only, although the guide page is pretty much helpful. Also I'm not yet experienced with hatch.

Would it be okay for me to take some time? If it's okay, I want to start working on it from today

p.s.) Also, my English is not that okay for I'm not using it as first language.

[stichbury]

Hi @kaestro Welcome to the project. Please take as long as you like to work on this. It's late here in the UK but I'll write you some basic instructions tomorrow to use Hatch and docs.

[kaestro]

@stichbury

sorry for the late contact. It's 6:45 am in Korea right now.

Thank you for the support, and have a good night!

[stichbury]

sorry for the late contact. It's 6:45 am in Korea right now. No problem at all! We are used to working asynchronously.

• My advice for working on a docs PR is to fork the repo, pip install vizro and install hatch with brew or pipx (as our docs describe).
• Before you make any changes, make sure you can build the docs. Navigate to the vizro-core folder of the code, as that's the package you'll mostly work on. In your terminal: hatch -v env create which should take a few minutes.
• Then try hatch run docs:serve and this should build the docs and serve them (copy the URL and paste it into your browser to see them running).

Any problems at this stage, please let us know!

Then you can modify the .md files to make any changes and save them. While the docs:serve is running, they docs will automatically rebuild and update. You'll need to keep an eye out for any warnings/errors though, as we build --strict so any change that's considered a problem will stop the server updating until you fix it and save that markdown again.

Good luck, and let us know how you get on.

[kaestro]

@stichbury

Thank you for all the supports. This project's CI is absolutely amazing, I'm really astonished.

Right now it's up and running.

BTW, do you want me to request pr after I feel like finished the task 1, or do you want me to request pr step by step? I wonder if there's some style suggested.

If there's none, I prefer the second

[stichbury]

Great news! We are really pleased you've found it easy to get up and running 👯

I think it would make sense, as it's your first time, to request a PR review after task 1, just so you can be sure of the end-to-end process. It's all very straightforward for docs but you'll need to run hatch run lint on your changes to make sure you've not introduced any issues that the style checker Vale objects to. Let's get you through the entire cycle once, and then future tasks (should you choose to accept them) you can be more self-contained.

Thanks again!

[kaestro]

It's me who's really thankful of.

Before I get started, I've found some questions hope I'm not bothering you too much to answer.

Right now, I'm reading Explore vizro page and having confusions on how to apply the documentation rule

the second and third part of documentation says that

1. don't repeat the internal links => which is not followed for api internal links are duplicated a lot in this page
2. consider how they will navigate from where they land in the API documentation back to the narrative content. => which is mostly not followed if I'm not losing it.

So, Q1 should I be removing the duplicates on this page? Or do you want me to leave the duplicates for APIs like this page.

Q2 Do you want me to add some links for those API links which can help users back to where their narrative content?

Q3 Do you have any commit conventions?

[stichbury]

So, Q1 should I be removing the duplicates on this page? Or do you want me to leave the duplicates for APIs like this page.

Good spot! But please leave that for now in favour of working on the task for this issue, which is to make the link text accessible and descriptive. Reason being that I am yet to edit some pages that will make revisions such as the ones you suggest here.

Q2 Do you want me to add some links for those API links which can help users back to where their narrative content?

Likewise, you can leave those for now, but thank you for offering.

Q3 Do you have any commit conventions?

I wouldn't worry too much about individual commits. I tend to group them together and commit small chunks for a particular page, feature or task, rather than all at once or random collection. So for example, I might commit changes to the nav of the docs in one and typo fixes in another, even though it's all the same PR to add a new page. Don't sweat it too much!

[kaestro]

@stichbury

Questions. Is it ok for me to remove some duplicate links that I think it would make better readability?

for example, what I'm trying to change is from this

into this

[kaestro]

Also, I've made some changes on explore vizro page and want to check whether this is what this issue wanted, and I'm following the style guide correctly.

72130f5751e1a9334fccc41f24decf1f48449016

Once again, thank you for all your supports and have a nice week

[stichbury]

Hi @kaestro all your edits look great to me, thank you. 🌟

[kaestro]

@stichbury

I think I'm about 50~60% done for vizro core and wonder if I might send a pull request to get reviews on whether I'm doing it properly. May I?

[stichbury]

Hi @kaestro Please do make a PR when you are ready! I'm out of office until Wednesday 8th May but one of the team can help if you need it, and may be able to offer you a review, but I will otherwise pick up on my return.

[antonymilne]

@stichbury should this ticket still remain open? At a glance, Task (3) definitely done now; Task (2) sounds like is not feasible; Task (1) was handled in #453 but maybe not fully?

If there's still some work to do but it's just a subset of the original ticket, please could you close this and open a new one for it so we can make it easier for any hacktoberfest participants to pick it up without needing to understand what's left to be done? 🙏

[stichbury]

@antonymilne I'll close this -- as you summarised, it's done for (3) and (2) was something the vale team couldn't particularly help with. Best to just keep an eye on links as we write new copy and review existing pages, and encourage the standards as we go.