Update content links to subprojects docs when they are published

[stichbury]

Description

#2600 is an overall task to move content from our separate packages (kedro-datasets and kedro-viz) into documentation subprojects.

We have a number of activities associated with that parent task, and this is one of them. We need to go through the entire set of documentation in the kedro project and confirm that all links to datasets and Viz docs are updated to point to the new location of the subproject docs.

[stichbury]

Kedro datasets docs: https://docs.kedro.org/projects/kedro-datasets/

[stichbury]

Note, we also need a set of redirects to be planned in advance for when we make the switch.

[stichbury]

I've started to think about how we tackle the wholesale switch to different docs subprojects. I want to record here how we'll format the links. We can use intersphinx linking but I'm wondering if this is suitably link checked (@astrojuanlu ?). By that, I mean, will it add a coupling between subprojects that we are actively seeking to remove by creating subprojects in the first place. That is, if we have docs with intersphinx linking, are we going to add a build dependency that chains our releases together again, as we have it right now in the Viz/datasets/framework docs? Could it make sense to instead use basic URL formatting with our existing link checker so that we are building against what is published here and now, and not what is on a particular branch? I am not sure I'm explaining myself very well, but wanted to see out advice before starting on this task.

Also, intersphinx link checking is horrific in terms of syntax. I'd rather not use it 😱 but of course we can educate our engineers and contributors to do so as needed.

Here's a table so we can add the formatting needed for each kind of link with an example page to use for the formatting.

	Framework doc page markdown example and API docs page example	Viz doc page example	Datasets docs example
Framework doc page	eg to API docs {py:class}`~kedro.config.OmegaConfigLoader`	{doc}`Visualisation <kedro-viz:kedro-viz_visualisation>`	{py:class}`json.JSONDataset <kedro_datasets.json.JSONDataset>`
Viz doc page	V -> F	internal links	V -> D
Datasets doc page	D -> F	D -> V	internal links

[astrojuanlu]

By that, I mean, will it add a coupling between subprojects that we are actively seeking to remove by creating subprojects in the first place.

Usually the intersphinx mapping is set to specific versions:

https://github.com/kedro-org/kedro-viz/blob/6e34745f63c3a5f91b4eae69e4b3283248e63440/docs/source/conf.py#L55-L57

This means that, even if project B makes a release and "breaks" something, this will not affect project A because it's using an older version of the docs.

The other advantage of using the intersphinx mapping is that it centralises said version. Otherwise our docs will be littered with links that sometimes use /latest, sometimes use /7.0.0, and so on.

And the third advantage is that, if and when we get rid of the not so nice plugins URLs #2600 (comment), we don't have to do a massive search & replace of all links using absolute URLs, and instead we only have to change the mapping once.

I agree the syntax is somewhat arcane, but the price of not using it is falling for all of the above 😅 Not a hill I'd like to die on but, since you asked, here's what I think.

[stichbury]

OK, gotcha. So basically we need to update the version in conf.py for each subproject release as we "accept" changes in other releases and want to step up to use them? Otherwise it's fixed to whatever we built against, rather than dynamic with the stable of the other project. OK. Neither is perfect but at least there's flexibility.

I will now update the table above with examples of each of the links. When you've a moment please could you review that I've got it right?

[astrojuanlu]

That's correct. And sure, will give it a look 👁️

[stichbury]

This is done for Framework and Viz (where possible, we have had to retain some of the absolute Viz links because they link to subhead permalinks). Datasets aren't using this yet, but the datasets project does have intersphinx linking enabled for the HF datasets.