Improve documentation about namespaces

[noklam]

Description

A long Slack thread and I found there are couples of things not explained clearly for modular pipeline.

Context

1. - it appears that parameters is namespaced too but I am not sure yet

• params was not namespaced but changed to namespace in 0.18 (breaking change) - See Add support for Stata datasets #971
• How to escape the namespace if one want to?

3. The docs use a cooking analogy which explain the modularity of pipeline, but there isn't any code example and it is quite hard to understand without playing with code. Diagrams like this could potentially helpful, at least this is how I learn.

The view of this documentation is significant.(for reference, API docs total view are around 2000)

[astrojuanlu]

Related (but not quite the same) #2633

[noklam]

#2839 Partially fix 1., but I think we need to improve this documentation.

[noklam]

Update the description and adding more backlink for context.

[noklam]

More evidence. https://linen-slack.kedro.org/t/14140948/hi-i-m-looking-at-namespaces-and-modular-pipelines-must-say-#cfa0d7eb-477b-4740-ab46-0682a6c04ebd

Hi, I’m looking at namespaces and modular pipelines. Must say, it’s somewhat confusing, and also some things seems to

have changed in newer versions of kedro.
For one, how should I understand this note a bit further down in the docs https://docs.kedro.org/en/0.18.12/nodes_and_pipelines/modular_pipelines.html#using-a-modular-pipeline-multiple-times
parameters references will not be namespaced, but params: references will.
In my mental model, it should not matter if I specify the whole parameter dictionary as “parameters” or if I give an individual element of it “params:elem”. This seems like a detail of how I implemented my node function. But indeed, when I tried this out, “params:elem”-type parameters will be “hidden” under the given namespace when creating a namespaced pipeline from a template one, while the “parameters” dict will stay global.
So basically “params:elem” and the “elem” attribute of “parameters” will refer to different values, for instance when I have a node function that takes input=["parameters", "params:elem"].
What’s the reasoning here, conceptually?
Thanks,
Viveca (edited)

[astrojuanlu]

Also related: #2723

[astrojuanlu]

Notice we used to have a "Namespace pipelines" page https://docs.kedro.org/en/0.17.7/03_tutorial/06_namespace_pipelines.html

[merelcht]

Did #3948 address this enough or do we want to spend more time on improving the docs for namespaces?

[astrojuanlu]

For the record https://docs.kedro.org/en/stable/nodes_and_pipelines/namespaces.html

Indeed further improvements can be made separately