Fix howto docs

[rkratky]

Description

This is a follow up to #429 -- don't merge before it.

Improve how-to docs:

• Move intro to how-to landing page
• Make headings consistently use "How to"
• Remove (post-build) "How to" from TOC

Checklist

• Runs make check successfully.
• Retains 100% code coverage (make check-coverage).
• N/A: New/changed keys in YAML format are documented.
• N/A: (Optional) Adds example YAML for new feature.
• (Optional) Closes an open bug in Launchpad. Fix FR-6139

[daniloegea]

Thanks, it looks good to me (only check the last commit).

[slyon]

Thanks, the changes are looking mostly good to me. But we hit some build failures. Locally, make run hits an endless loop and I see a failure on the readthedocs CI, which might be related to doc/howtos.sh being incomplete. (Some of which might already be fixed in #429)

I also left some inline comments.

[rkratky]

@slyon This is finally building successfully on RTD, so I believe it's good to merge (after #429).

[rkratky]

@slyon This is finally building successfully on RTD, so I believe it's good to merge (after #429).

Thanks, the changes are looking mostly good to me. But we hit some build failures. Locally, make run hits an endless loop and I see a failure on the readthedocs CI, which might be related to doc/howtos.sh being incomplete. (Some of which might already be fixed in #429)

I also left some inline comments.

Thanks. I was aware of those problems. Should be fixed now.

[slyon]

@rkratky Could you please rebase this branch on top of main, in order to resolve the merge conflicts?

[rkratky]

@rkratky Could you please rebase this branch on top of main, in order to resolve the merge conflicts?

Done. Sorry for the mess :)

[slyon]

I guess we could squash both commits into "Improve how-to docs" (or I can do a squash merge). The first commit seems to be a left-over from the rebase.

Also see my inline comments for a few final nitpicks before we can merge this.

[slyon]

Thanks a lot for cleaning it all up! ❤️
LGTM.