Add a newcomer tutorial

[llucax]

This PR adds a new "Tutorials" documentation section, including a new tutorial for newcomers with no Python experience.

[Copilot]

Pull Request Overview

This PR adds a new "Tutorials" documentation section with a comprehensive newcomer tutorial designed for users with no Python experience. The tutorial covers the complete setup process from installing VS Code to creating API keys and initializing the client.

• Adds a newcomer tutorial covering environment setup, API key creation, and client initialization
• Updates documentation configuration to support GitHub-style callouts
• Reformats code style in pyproject.toml for consistency

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/tutorials/newcomer.md	New comprehensive tutorial for Python newcomers with step-by-step setup instructions
docs/SUMMARY.md	Adds Tutorials section to documentation navigation
README.md	Adds reference to newcomer tutorial with helpful callout
mkdocs.yml	Enables github-callouts markdown extension for enhanced documentation
pyproject.toml	Reformats dependencies and keywords for better readability, adds markdown-callouts package

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[llucax]

Replaces #219, as agreed with @merlin-esser-frequenz.

[cwasicki]

@llucax On first glimpse it looks like none of the comments in #219 have been addressed. What is the reason to open a new PR and why in the reporting client repo?

[llucax]

So, my suggestion was that most of the original tutorial was OK, it was just not something to put in the README. This PR does that, moves the instructions to a dedicated "Tutorial for newcomers", where I think it makes sense to give very opinionated instructions and even suggestions on how to use it to build notebooks, etc.

Since nobody opposed to this suggestion (Tom was the only one to react to it and he did with a 👍) and the PR seemed stalled, I decided to push for it myself so Merlin's work doesn't go to waste, as again I think it is very useful to introduce non (Python) programmers on how to use the reporting API.

So I guess we have a couple of high-level questions here:

1. Do we want to provide a guide like this?

   The answer for this one for me is pretty much a irrefutable YES, as Merlin created it out of necessity. There are people with no prior knowledge that need to be introduced to use the reporting API.

2. Where do we want to put this?

   Keeping it in this repo was the easiest option as deciding where else to put it might mean we keep stalling the addition of this guide. I think having it in this repo is OK, but I'm also opened to put it somewhere else.

3. Do we want to split this further?

   Maybe splitting out "Setting up dev environment for newbies" that focus only on that, so we can reuse in other repos. For me this is also a yes, but requires more work and find a place, etc. So again, I think it will make the addition of the guide stall.

In general I think merging this in this repo is a step forward, and we can build on top of it instead of not merging anything until it is perfect, but I'm also opened to alternatives.

[cwasicki]

So, #219 (review) was that most of the original tutorial was OK

There are various issues in these docs, including bugs. All discussed in the old PR.

Do we want to provide a guide like this?

At least we would need to provide a link to a guide like this. If we want to maintain it also, I would expect that the commands can be copy-pasted by people without dev background and work out-of-the box on almost all machines.

Where do we want to put this?

You suggested https://github.com/frequenz-floss/docs/, that sounds like a good idea.

Do we want to split this further?

I would strongly vote for this. To me there are the following main parts:

1. Setting up a python dev environment. This has nothing to do with frequenz at all. -> docs, or just a link elsewhere
2. Notes about frequenz APIs, keys, UI. Relevant for all APIs. -> docs
3. The reporting-specific part is mostly a copy of the existing README. Couple of clarifications we can just pull into the README. -> this repo
4. The part about using notebooks. It's short, but very valuable for non-devs to get started. Still would move it to the docs but prominently advertise it's usage also in this repo's README.

[llucax]

There are various issues in these docs, including bugs. All discussed in the old PR.

I went again through all the comments and I found only 2 bugs I missed when redoing the PR (ipkernel -> ipykernel, and removing the unused pandas package and import, both fixed in the fixup commit).

All other comments are about stuff not being appropriate for the README (which is addressed by this PR), about being too opinionated and suggesting more stuff than what is strictly necessary to use this library (which is also addressed in this PR by making it a newcomer's guide, which says explicitly it is opinionated as the goal is to introduce outsiders, not to be neutral for seasoned developers), and about splitting common parts that could apply to many other open source projects and move that to frequenz-floss/docs as you pointed out (which I suggest doing as a second step, after merging this PR).

If there are more issue, please point them out individually, as I couldn't find any others.

Do we want to split this further?

I would strongly vote for this

Me too, but there is a bandwidth problem. I did this PR because it was a low-hanging fruit and I thought it brings value (i.e. the point we are at with this PR merged is better than the point we are without this PR merged, which doesn't mean it is the point where we really want to be long term).