Improve documentation about configuration (first draft by development team)

[merelcht]

Description

The chapter on configuration is very long and contains a lot of information: https://kedro.readthedocs.io/en/stable/kedro_project_setup/configuration.html

We should divide this up in a better way.

Possible Implementation

From Kedro 0.18.5 the sections in the configuration chapter are:
Configuration

1. Configuration root
2. Local and base configuration environments
3. Additional configuration environments
4. Template configuration
   • Globals
   • Jinja2 support
5. Configuration with OmegaConf
   • Templating for parameters
6. Parameters
   • Load parameters
   • Specify parameters at runtime
   • Use parameters
7. Credentials
   • AWS credentials
8. Configure kedro run arguments

Maybe we could divide so that we talk about the different types of config: catalog, parameters, credentials and logging and then separately about the specific loaders which go into templating and omegaconf.

[stichbury]

When I read the page last week, the thing that struck me most was that we were saying how it worked rather than how to use it. I wonder if a set of pages of "recipes" for different configuration options may work? I don't feel like we have a good example of using config really, since spaceflights doesn't really modify/extend what is there.

[stichbury]

Thinking more about this issue because I want to get some changes into the upcoming sprint starting w/c 6th March 2023.

I'm considering separating the page into a group as follows:

• Configuration management with Kedro
  • "What Kedro does to help you" or "Why use Kedro for config" sort of thing -- not marketing, but clear explanation of how you benefit
• Configuration basics
  • Config root
  • Configuration environments
• Kedro configuration how-to guide
  • How to do various config tasks (from simple to more complex use cases)
• Configuration FAQs

[stichbury]

The above is not an exhaustive list nor is it in any way definite -- it's just the kind of information I'd probably look for.

What I'd particularly like to see is a few examples (in code) of how to work with configuration in Kedro, as I don't feel we have any right now.

[astrojuanlu]

Maybe we could divide so that we talk about the different types of config: catalog, parameters, credentials and logging

In fact, I'm testing gh-2375 and I'm getting confused about the different places where we store "configuration":

• Top-level pyproject.toml for [tool.kedro] config
• conf/ (with base and local by default) for "config files"
• src/{package_name}/settings.py for "project settings"

[merelcht]

Yes I think we need to better define what "configuration" is exactly. I wouldn't consider pyproject.toml Kedro configuration, because it's more general python config, but I do get why someone might think it's also part of the "configuration" we talk about in the docs.