Add first chapter of flow-by-example to docs

[spartan0x117]

PR Description

Adds the first section of flow-by-example to the docs. Note I'm not super familiar with the metadata at the top of the docs, but when looking at the docs locally everything seemed reasonable.

Notes to the Reviewer

@clayton-cornell where would be the most appropriate place to include the docker-compose so users can easily use it?

PR Checklist

• Documentation added

[clayton-cornell]

@spartan0x117 We can include the YAML in the same directory as the tutorial, or you can add it to an assets directory similar to what has been done here: https://github.com/grafana/agent/tree/main/docs/sources/flow/tutorials/assets

[clayton-cornell]

We should move all the screenshots/diagrams to the right location: https://grafana.com/docs/writers-toolkit/write/image-guidelines/#where-to-store-media-assets

[rfratto]

Do the existing tutorials still hold educational value? Should this fully supplant the existing tutorials?

[clayton-cornell]

Do the existing tutorials still hold educational value? Should this fully supplant the existing tutorials?

My take on it... they should be removed or re-worked into a more comprehensive tutorials.

[spartan0x117]

If we go that route, should that be done in this PR or a separate one?

[clayton-cornell]

If we go that route, should that be done in this PR or a separate one?

I'd say a separate PR... otherwise we overload this one with scope creep. :-)

[spartan0x117]

I made a few changes after more carefully going through the writer's toolkit, mostly as individual commits that we can back out, if needed:

• I used a collapse shortcode for the solution rather than a downloadable file. Someone could copy-paste it if they wanted, but this also allows them to just view it easily. (I should probably also do this with the docker-compose.yaml).
• I also changed the list to be a repetitive list, and for styling I pushed the paragraph to a new line.
• Switched Headline Case -> Sentence case wherever I saw it.
• Replaced relref links with full urls, per the writer's toolkit on links and added the <AGENT_VERSION> to them.

[clayton-cornell]

• I used a collapse shortcode for the solution rather than a downloadable file.

There's also a (default available) Collapse/Expand code thing for code snippets in codefence markdown. Longer code blocks are automatically collpased so that codeblocks don't eat up huge amounts of screen space :-)

[spartan0x117]

Good to know! 😄 In this case I was aiming to hide it entirely unless a reader wants to see a potential solution (and do so ideally without having to leave the page).

[github-actions]

This PR has not had any activity in the past 30 days, so the needs-attention label has been added to it.
If you do not have enough time to follow up on this PR or you think it's no longer relevant, consider closing it.
The needs-attention label signals to maintainers that something has fallen through the cracks. No action is needed by you; your PR will be kept open and you do not have to respond to this comment. The label will be removed the next time this job runs if there is new activity.
Thank you for your contributions!

[clayton-cornell]

@spartan0x117 Are we done here? I think the docs are good enough to publish as-is.. get the info out there and we can update as needed.

[spartan0x117]

Yeah I think this one should be good to go! I can merge on Monday and then work on adding the other tutorial sections 😃

[clayton-cornell]

@spartan0x117 Merged it

[grafanabot]

The backport to release-v0.39 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new branch
git switch --create backport-5888-to-release-v0.39 origin/release-v0.39
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x 77aac507124cdf2d5aef2bbfb5d7ec7024a33daf
# Push it to GitHub
git push --set-upstream origin backport-5888-to-release-v0.39
git switch main
# Remove the local backport branch
git branch -D backport-5888-to-release-v0.39

Then, create a pull request where the base branch is release-v0.39 and the compare/head branch is backport-5888-to-release-v0.39.