Improve documentation

[basdgrt]

The documentation seems a bit outdated in some places. Other than that I think we can also make some improvements to the overall structure, as some things are explained multiple times at the moment.

Proposed structure

• Introduction: The unique selling points and advantages of Baker
• Quick start guide: overview of required dependencies and module structure
• Tutorial: A short tutorial that can be completed in < 30 minutes. Creating a simple recipe and firing some sensory events. A slimmed down version of what we currently have under "Development Life Cycle"
• Core Concepts: A section dedicated fully to the 3 main concepts in Baker. events, ingredients, and recipes.
• Cookbook: A collection of things you can do with recipes. Quite similar to what we have under the "Recipe DSLs" section at the moment.
• Running in production: Things you might want to know if you consider running Baker in production. Stuff like testing, configuration, monitoring, error handling, and resolving failed recipes.
• Reference: This is where we go deep into nitty gritty details for the user who wants to know everything.

Other possible improvements

Type safe code samples

All code samples are written in Markdown files. If we change the actual implementation we might not notice the docs become outdated. Ideally the examples come from compiled snippets. I think we can achieve that via the "snippets" extension.

Register extension:

markdown_extensions:
  - pymdownx.snippets:
      base_path: docs

Load snippet:

  --8<-- "myfile.txt"

More info here: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets

Tooltips in code samples

Mkdocs has the option to add tooltips to your code samples. I think this looks nicer than the comments we use now. Don't know how well this works in combination with the type safe code samples though.

[basdgrt]

Will be merged as part of the 4.0.0 release.