docs: how to use pebble api

[IronCore864]

Add a new how-to guide for Pebble and refactor existing Pebble API introduction content as reusable content.

Preview: https://canonical-pebble--545.com.readthedocs.build/en/545/how-to/use-the-pebble-api/

[dwilding]

Capturing my initial thoughts before I do a more detailed review (not today):

• The doc is based around a scenario of dynamically setting up a service configuration in the context of CI. I think we should present this as the purpose of the doc. So perhaps the title could be "How to use the Pebble API for automated service testing". The short title could be "Automate service testing".

• If we present the doc this ^ way, the introduction should state that the purpose of the doc is to demonstrate how to programmatically set up a service configuration, run tests against the services, then tear down the configuration.

• There seems to be some overlap between the introduction and the "API and automated workflows" section. Since this is a how-to doc, I'd move as much of the explanation into the "API and automated workflows" section (keeping it brief) and make the introduction shorter & focused on the purpose of the doc.

• Before the examples of using the API, should we mention how to make sure that Pebble is available in the environment? What I mean is - in the context of CI, how do we recommend that Pebble gets installed?

• The doc talks about using Pebble as a more robust alternative to shell scripts, but then the first examples we give are curl. On the surface, it doesn't appear much more robust/structured than using shell scripts. Should we take a stronger position and say that Go or Python is the recommended approach? We could still include curl, but I don't think we should lead with it.

• In the code examples, would it be possible to include a demo of how to run a couple of tests against the services? I know it might be difficult without specific services in mind... Maybe we could have a comment that said something like "Suppose that service 'svc1' exposes an HTTP API on port 5000" then include a code snippet of how to check that a particular endpoint such as /version returns 200. It doesn't need to be super realistic - just something to make this step more concrete.

[IronCore864]

Capturing my initial thoughts before I do a more detailed review (not today):

• The doc is based around a scenario of dynamically setting up a service configuration in the context of CI. I think we should present this as the purpose of the doc. So perhaps the title could be "How to use the Pebble API for automated service testing". The short title could be "Automate service testing".
• If we present the doc this ^ way, the introduction should state that the purpose of the doc is to demonstrate how to programmatically set up a service configuration, run tests against the services, then tear down the configuration.
• There seems to be some overlap between the introduction and the "API and automated workflows" section. Since this is a how-to doc, I'd move as much of the explanation into the "API and automated workflows" section (keeping it brief) and make the introduction shorter & focused on the purpose of the doc.
• Before the examples of using the API, should we mention how to make sure that Pebble is available in the environment? What I mean is - in the context of CI, how do we recommend that Pebble gets installed?
• The doc talks about using Pebble as a more robust alternative to shell scripts, but then the first examples we give are curl. On the surface, it doesn't appear much more robust/structured than using shell scripts. Should we take a stronger position and say that Go or Python is the recommended approach? We could still include curl, but I don't think we should lead with it.
• In the code examples, would it be possible to include a demo of how to run a couple of tests against the services? I know it might be difficult without specific services in mind... Maybe we could have a comment that said something like "Suppose that service 'svc1' exposes an HTTP API on port 5000" then include a code snippet of how to check that a particular endpoint such as /version returns 200. It doesn't need to be super realistic - just something to make this step more concrete.

On the title:

I think we should base this how-to on a scenario, which is also what we discussed earlier when talking about Pebble how-to guide ideas, see the doc here (internal only, sorry).

The scenario in the example is indeed "Automate service testing", but the same pattern can be used in anything that needs to be automated. So maybe using "Automate service testing" as the title would be too narrow, because if I'm a user of Pebble and I want to use Pebble for some automation work but not automated testing, seeing this title would not attract me and I might not click on it.

On making Pebble available in the env:

I think "how to make Pebble available in the CI env" is a tricky question to answer, mostly because there is no right answer because the CI runner could be a VM where Pebble can be installed in many ways: manual/configuration management/built in the custom image, or it could be an OCI image where Pebble is or is not the entrypoint. Maybe we want to recommend using a container CI runner with Pebble as the entrypoint (from Canonical's standpoint), but it is too opinionated and may only be preferred/known by/to rock/charm users.

So, how about we only slightly mention that it must be available as a prerequisite, list a few options, but don't recommend a specific one?

On adding more steps to run tests:

For similar reasons, some detailed steps (or even some mocks) to run some tests are not included, because there are many ways. Maybe the user doesn't want to trigger the tests in one script. Maybe the users can have a setup script, then run a test in a different step, then another step for the teardown. The applications could be endless.

What's more, I think the goal of a how-to is not to provide something the user can copy-paste and reproduce (that would be the goal of a tutorial), but to show how to use some feature and why this feature can be useful.

On the order of the ways to access the API:

Compared to systemd, the API is a strong selling point, but it's not logical to put curl in the first place. However, not leading with curl is a bit tricky because it's the most well-known and easy-to-start method for API access.

Thoughts? Shall we reorder it to something like Python-Go-curl? (Ranking Python before Go purely because of the TIOBE index).

[dwilding]

I'm adding suggestions on specific parts.

To continue the discussion of the general comments:

• For the long title, how about "How to use the Pebble API to manage services". And for the short title "Use the Pebble API". I like what you said about having an attractive title.

• Thinking about what you said about installing Pebble, I think it's best if we don't add anything about this. We already have "Install Pebble" as the first item under "How-to guides" in the menu. Like you said for another point, this new doc isn't a tutorial - it's supposed to be focused on the API.

• Let's see what Ben thinks, but I also feel the order should be Python, Go, curl. (BTW, in the API reference doc it makes sense to put curl first, because people may be manually trying out different endpoints, and curl is quick to do that.)

[dwilding]

I've finished adding comments on specific parts. There are two main refactoring suggestions here and here.

Copying the outstanding discussion points from earlier:

• Title - For the long title, how about "How to use the Pebble API to manage services". And for the short title "Use the Pebble API". I like what you said about having an attractive title.
• Order of examples - Let's see what Ben thinks, but I also feel the order should be Python, Go, curl.

[benhoyt]

Note that the docs build is failing now.

[IronCore864]

Refactored after our discussion. Changes:

• Reduced the introduction part.
• Removed Go and curl examples, and added a link to the API reference doc.
• Removed the wait change part in the Python example, and added a comment.
• Merged the latest master to pull in the API reference doc.

[dwilding]

Nice new doc, thanks! I've finished reviewing

[benhoyt]

A couple of minor comments, and one comment about not trying to reuse content between reference and how-to. But this is looking very good now, thanks.

[benhoyt]

One nit suggestion, but this looks good to me -- approved!