docs: add top-level intro and module-level intros

[dimaqq]

Docs: Ops: Add top-level intro, clean up ops.module intro in light of that, flesh out ops.pebble and ops.testing intros a bit more

https://warthogs.atlassian.net/browse/CHARMTECH-183

• "home page" library reference
• ops module
• ops.main entry point
• ops.pebble module
• ops.testing module

[dimaqq]

Also fixes #1263

[dimaqq]

@tmihoc the PR is mostly ready for your review.
(except the OPT1/OPT2 to be discussed with the team)

[benhoyt]

Looks good, just two more minor suggestions, but I'm happy to merge. Thanks!

[tmihoc]

I was looking at the published result and just noticed that, while the top-level intro starts with ops.main entry point, the Navigation / order of the sections starts with ops module, and only then the entry point. I'm not sure which one is better but I feel we should be consistent. PS Judging by what we had in the Charm SDK docs, we should start with the entrypoint. Basically, the minute people write import ops at the top, they should follow up with the main bit, which should anticipate the charm class argument:

ops.main()
The Ops library provides a top-level main method. This method should be the main entrypoint for your charm, like so:

import ops

# ... charm code

if __name__ == "__main__":
  ops.main(HelloCharm)
The method takes a charm class (see the next section) as an argument, and is used to initialise the charm code when the charm is invoked and ensure that events are dispatched to the charm in response to controller-emitted events.

(To clarify, I'm not suggesting we change anything about the text on https://ops.readthedocs.io/en/latest/#ops.Framework -- just the order of the ops.main entrypoint vs. ops module.)

Sorry I only noticed now.

[tonyandrewmeyer]

I was looking at the published result and just noticed that, while the top-level intro starts with ops.main entry point, the Navigation / order of the sections starts with ops module, and only then the entry point. I'm not sure which one is better but I feel we should be consistent.

@benhoyt noticed this in #1381 as well, so I've adjusted it there. We went with ops first and then ops.main, because most of the time when people come to the reference docs, they'll be wanting something in ops. Once you know how to use ops.main (which you probably got from the tutorial, and then the code from charmcraft init), you'll almost never want to look at its reference docs.

[tmihoc]

Once you know how to use ops.main (which you probably got from the tutorial, and then the code from charmcraft init), you'll almost never want to look at its reference docs.

While that's true, in principle, content should always have an obvious order, either natural (numerical, for tightly ordered things, or lifecycle, for more loosely ordered things) or, if that's not possible alphabetical. Here I'd use natural order at the high levels and alphabetical within. So,

• ops (natural order:)
  • ops.main entrypoint
  • ops.main (alphabetical order:)
    • ActionEvent
    • ...
  • ops.pebble
  • ops.testing
  • ops.testing.harness (legacy)

So that's the order I would use.

That is, imo, the fact that ops.main entrypoint is something you only use once shouldn't affect placement.