docs: update how-to guides to use the new unit testing framework

[tonyandrewmeyer]

Adjustments to the how-to guides:

• Links to the API reference are updated to the new location. I assume that these can be references that will automatically resolve somehow, but I'm not sure how to do that, so I opened Make internal doc links references #1506 and just fixed them as full links for now (at least they'll work again).
• A few minor whitespace cleanups.
• Removed all the Harness sections, moving the Scenario sections up to be "unit tests"
• Updated the Scenario sections to use ops.testing and Scenario 7
• Updated the secrets how-to to be more explicit about needing to remove revisions if you create new ones.

Live preview

[tonyandrewmeyer]

I weirdly get this locally when I build:

/home/tameyer/code/operator/ops/charm.py:docstring of ops.CharmBase.charm_dir:1: WARNING: py:class reference target not found: pathlib._local.Path [ref.class]
[...]
/home/tameyer/code/operator/ops/_private/harness.py:docstring of ops._private.harness.Harness.get_filesystem_root:1: WARNING: py:class reference target not found: pathlib._local.Path [ref.class]

It doesn't seem like any changes to the how-to guides should cause that. I'll investigate further.

[tonyandrewmeyer]

I also get it in main, and in Dora's branch that was just merged in with all the new docs. But I'm sure I re-built the docs in that branch before approving the review, and the rtd CI didn't fail. 😕

[tonyandrewmeyer]

Hmm, maybe @dimaqq already found this? sphinx-doc/sphinx#12715

[tonyandrewmeyer]

Hmm, maybe @dimaqq already found this? sphinx-doc/sphinx#12715

Yes, running tox with an older Python 'fixes' it.

[tonyandrewmeyer]

@tmihoc feel free to review if you have time, but no worries if not :)

[tmihoc]

This is massive, thanks, Tony!

PS Thanks also for updating the ops reference links and touching up the language in a lot of other places.

Let of a couple of teeny-tiny comments -- the one at the top about the path for the scenario testing doc is maybe the most relevant at this time.

[tmihoc]

Thanks for updating the reference links! PS Some day I think we should switch to relative paths everywhere. That way moving those reference docs around will no longer break things.

[tonyandrewmeyer]

Some day I think we should switch to relative paths everywhere. That way moving those reference docs around will no longer break things.

Agreed. I think we can do better than just relative paths and actually use references, but I'm not sure how to do that in the combination of ReST and myst-markdown. So I opened #1506 so that it's someone else's (maybe future-Tony, maybe not) problem 😆 .

[james-garner-canonical]

Look good, just a couple of minor (non-blocking) comments

[dwilding]

Thanks for doing all of this! - No extra comments from me