docs: make requested changes

canonical · Dec 17, 2024 · b53d96a · b53d96a
1 parent f2538b9
commit b53d96a
Show file tree

Hide file tree

Showing 37 changed files with 287 additions and 267 deletions.
diff --git a/docs/custom_conf.py b/docs/custom_conf.py
@@ -59,9 +59,9 @@
 
 # FIXME: temporarily disable missing xrefs in this branch, until the missing
 # links to Juju and Charmcraft are added.
-suppress_warnings = [
-    'myst.xref_missing',
-]
+#suppress_warnings = [
+#    'myst.xref_missing',
+#]
 
 ############################################################
 ### Project information

diff --git a/docs/reference/charm-relation-interfaces.md → .../explanation/charm-relation-interfaces.md b/docs/reference/charm-relation-interfaces.md → .../explanation/charm-relation-interfaces.md
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -4,6 +4,9 @@
 ```{toctree}
 :maxdepth: 1
 
+charm-relation-interfaces
+testing
+interface-tests
 holistic-vs-delta-charms
 how-and-when-to-defer-events
 storedstate-uses-limitations

diff --git a/docs/reference/interface-tests.md → docs/explanation/interface-tests.md b/docs/reference/interface-tests.md → docs/explanation/interface-tests.md
diff --git a/docs/reference/testing.md → docs/explanation/testing.md b/docs/reference/testing.md → docs/explanation/testing.md
@@ -83,6 +83,28 @@ When writing an integration test, it is not sufficient to simply check that Juju
 - [pytest-operator](https://github.com/charmed-kubernetes/pytest-operator) and/or [`zaza`](https://github.com/openstack-charmers/zaza)
 
 
+(pytest-operator)=
+### `pytest-operator`
+
+`pytest-operator` is a Python library that provides Juju plugins for the generic Python library `pytest` to facilitate the {ref}`integration testing <integration-testing>` of charms.
+
+> See more: [`pytest-operator`](https://github.com/charmed-kubernetes/pytest-operator)
+
+It builds a fixture called `ops_test` that helps you interact with Juju through constructs that wrap around [`python-libjuju` ](https://pypi.org/project/juju/).
+
+> See more: 
+> - [`pytest-operator` > `ops_test`](https://github.com/charmed-kubernetes/pytest-operator/blob/main/docs/reference.md#ops_test) 
+> - [`pytest` > Fixtures](https://docs.pytest.org/en/6.2.x/fixture.html)
+
+It also provides convenient markers and command line parameters (e.g., the `@pytest.mark.skip_if_deployed` marker in combination with the `--no-deploy` configuration helps you skip, e.g., a deployment test in the case where you already have a deployment).
+
+
+> See more:
+> - [`pytest-operator` > Markers](https://github.com/charmed-kubernetes/pytest-operator/blob/main/docs/reference.md#markers)
+> - [`pytest-operator` > Command line parameters](https://github.com/charmed-kubernetes/pytest-operator/blob/main/docs/reference.md#command-line-parameters)
+
+
+
 **Examples.**
 
 - [https://github.com/canonical/prometheus-k8s-operator/blob/main/tests/integration/test_charm.py](https://github.com/canonical/prometheus-k8s-operator/blob/main/tests/integration/test_charm.py)

diff --git a/docs/howto/get-started-with-charm-testing.md b/docs/howto/get-started-with-charm-testing.md
@@ -6,7 +6,7 @@ Testing charm code is an essential part of charming. Here we will see how to get
 **What you'll need:**
 - knowledge of testing in general
 - knowledge of Juju and charms
-- knowledge of the Juju models and events, esp. the data involved in a charm's lifecycle (e.g. see [Talking to a workload control flow from A to Z]())
+- knowledge of the Juju models and events, esp. the data involved in a charm's lifecycle
 
 **What you will learn:**
 - What are the starting points for adding tests to a charm?
@@ -77,7 +77,9 @@ If the charm is a machine charm, workload operation calls can be done directly,
 
 "Juju operations" are the most 'meta' of them all: they do not affect the workload in and of itself, but they share data which is meant to affect the operation of *other* charms that this charm is integrated with.
 
+<!-- UPDATE LINKS:
 > See more: [Talking to a workload: control flow from A to Z](), [Charm lifecycle]() 
+-->
 
 ### What we are testing when we unit-test
 
@@ -120,7 +122,9 @@ There are two ways to initialize a harnessed charm:
  * When a charm is deployed, it goes through the Setup phase, a fixed sequence of events. `Harness` has a method, `begin_with_initial_hooks()`, that runs this sequence.
  * Alternatively, you can initialise the charm by calling `begin()`. This will instantiate the charm without firing any Setup phase event.
 
+<!-- UPDATE LINKS:
 > See more: [A charm's life](), [`ops.testing.Harness.begin_with_initial_hooks()`](https://ops.readthedocs.io/en/latest/harness.html#ops.testing.Harness.begin_with_initial_hooks), [`ops.testing.Harness.begin()`](https://ops.readthedocs.io/en/latest/harness.html#ops.testing.Harness.begin)
+-->
 
 After the Setup phase, the charm goes into Operation. To test operation-phase-related events, the harness provides some methods to simulate the most common scenarios. For example: 
 

diff --git a/docs/howto/index.md b/docs/howto/index.md
@@ -1,4 +1,4 @@
-(howto-guides)=
+(how-to-guides)=
 # How-to guides
 
 ```{toctree}
@@ -22,7 +22,6 @@ Get started with charm testing <get-started-with-charm-testing>
 Write unit tests for a charm <write-unit-tests-for-a-charm>
 Write scenario tests for a charm <write-scenario-tests-for-a-charm>
 Write integration tests for a charm <write-integration-tests-for-a-charm>
-Instrument your charm with tracing telemetry <instrument-your-charm-with-tracing-telemetry>
 Turn a hooks-based charm into an ops charm <turn-a-hooks-based-charm-into-an-ops-charm>
 
 ```

diff --git a/docs/howto/instrument-your-charm-with-tracing-telemetry.md b/docs/howto/instrument-your-charm-with-tracing-telemetry.md
diff --git a/docs/howto/manage-actions.md b/docs/howto/manage-actions.md
@@ -1,8 +1,9 @@
 (manage-actions)=
 # How to manage actions
 
+<!-- UPDATE LINKS
 > See first: [`juju` | Action](https://juju.is/docs/juju/action), [`juju` | Manage actions](https://juju.is/docs/juju/manage-actions), [`charmcraft` | Manage actions]()
-
+-->
 
 ## Implement the feature
 

diff --git a/docs/howto/manage-configurations.md b/docs/howto/manage-configurations.md
@@ -1,7 +1,9 @@
 (manage-configurations)=
 # Manage configurations
 
+<!-- UPDATE LINKS:
 > See first: [`juju` | Application configuration](https://juju.is/docs/juju/configuration#heading--application-configuration), [`juju` | Manage application configurations](https://juju.is/docs/juju/manage-applications#heading--configure-an-application), [`charmcraft` | Manage configurations]()
+-->
 
 
 ## Implement the feature

diff --git a/docs/howto/manage-interfaces.md b/docs/howto/manage-interfaces.md
@@ -332,7 +332,7 @@ You should see:
 
 In particular, pay attention to the `provider` field. If it says `<no tests>` then there is something wrong with your setup, and the collector isn't able to find your test or identify it as a valid test.
 
-Similarly, you can add tests for requirer in `./interfaces/my_fancy_database/v0/interface_tests/test_requirer.py`. Don't forget to edit the `interface.yaml` file in the "requirers" section to add the name of the charm and the URL. See the "Edit `interface.yaml`" section in the previous how-to guide [How to register an interface]() for more detail on editing `interface.yaml`. [Here](https://github.com/IronCore864/charm-relation-interfaces/tree/my-fancy-database/interfaces/my_fancy_database/v0) is an example of tests for requirers added.
+Similarly, you can add tests for requirer in `./interfaces/my_fancy_database/v0/interface_tests/test_requirer.py`. Don't forget to edit the `interface.yaml` file in the "requirers" section to add the name of the charm and the URL. See the "Edit `interface.yaml`" section in the previous how-to guide "How to register an interface" for more detail on editing `interface.yaml`. [Here](https://github.com/IronCore864/charm-relation-interfaces/tree/my-fancy-database/interfaces/my_fancy_database/v0) is an example of tests for requirers added.
 
 ### Merge in charm-relation-interfaces
 
@@ -451,7 +451,7 @@ INFO:root:Running tests for role: provider
 }
 ```
 
-For reference, [here](https://github.com/IronCore864/my-fancy-database-operator) is an example of a bare minimum `my-fancy-database-operator` charm to make the test pass. In the charm, application relation data and unit relation data are set according to our definition (see the beginning part of the previous how-to guide [How to register an interface]().
+For reference, [here](https://github.com/IronCore864/my-fancy-database-operator) is an example of a bare minimum `my-fancy-database-operator` charm to make the test pass. In the charm, application relation data and unit relation data are set according to our definition (see the beginning part of the previous how-to guide "How to register an interface".
 
 ### Troubleshooting and debugging the tests
 

diff --git a/docs/howto/manage-leadership-changes.md b/docs/howto/manage-leadership-changes.md
@@ -1,8 +1,9 @@
 (manage-leadership-changes)=
 # Manage leadership changes
 
+<!-- UPDATE LINKS:
 > See first: [`juju` | Leader](https://juju.is/docs/juju/leader)
-
+-->
 
 ## Implement response to leadership changes
 

diff --git a/docs/howto/manage-libraries.md b/docs/howto/manage-libraries.md
@@ -1,7 +1,9 @@
 (manage-libraries)=
 # Manage libraries
-> See first: [`juju` | Library](), [`charmcraft` | Manage libraries]()
 
+<!-- UPDATE LINKS:
+> See first: [`juju` | Library](), [`charmcraft` | Manage libraries]()
+-->
 
 ## Write a library
 

diff --git a/docs/howto/manage-logs.md b/docs/howto/manage-logs.md
@@ -1,7 +1,9 @@
 (how-to-log-a-message-in-a-charm)=
 # How to log a message in a charm
 
+<!-- UPDATE LINKS:
 > See first: [`juju` | Log](https://juju.is/docs/juju/log), [`juju` | How to manage logs > Manage the logging configuration](https://juju.is/docs/juju/manage-logs#heading--manage-the-logging-configuration)
+-->
 
 <!--
 > 

diff --git a/docs/howto/manage-relations.md b/docs/howto/manage-relations.md
@@ -3,7 +3,9 @@
 
 To add integration capabilities to a charm, you’ll have to define the relation in your charm’s charmcraft.yaml file and then add relation event handlers in your charm’s `src/charm.py` file.
 
+<!-- UPDATE LINKS
 > See first: [`juju` | Relation (integration)](https://juju.is/docs/juju/relation), [`juju` | Manage relations](https://juju.is/docs/juju/manage-relations), [`charmcraft` | Manage relations]()
+-->
 
 ## Implement the feature
 

diff --git a/docs/howto/manage-resources.md b/docs/howto/manage-resources.md
@@ -1,7 +1,9 @@
 (manage-resources)=
 # How to manage resources
 
+<!-- UPDATE LINKS:
 > See also: [`juju` | Resource (charm)](https://juju.is/docs/juju/charm-resource), [`juju` | Manage resources](https://juju.is/docs/juju/manage-charm-resources), [`charmcraft` | Manage resources]()
+-->
 
 ## Implement the feature
 

diff --git a/docs/howto/manage-secrets.md b/docs/howto/manage-secrets.md
@@ -1,7 +1,9 @@
 (manage-secrets)=
 # How to manage secrets
 
+<!-- UPDATE LINKS:
 > See first: [`juju` | Secret](https://juju.is/docs/juju/secret), [`juju` | Manage secrets](https://juju.is/docs/juju/manage-secrets), [`charmcraft` | Manage secrets]()
+-->
 
 > Added in `ops 2.0.0`, `juju 3.0.2`
 

diff --git a/docs/howto/manage-storage.md b/docs/howto/manage-storage.md
@@ -1,7 +1,9 @@
 (manage-storage)=
 # How to manage storage
 
+<!-- UPDATE LINKS:
 > See first: [`juju` | Storage](https://juju.is/docs/juju/storage), [`juju` | Manage storage](https://juju.is/docs/juju/manage-storage), [`charmcraft | Manage storage]()
+-->
 
 ## Implement the feature
 

diff --git a/docs/howto/turn-a-hooks-based-charm-into-an-ops-charm.md b/docs/howto/turn-a-hooks-based-charm-into-an-ops-charm.md
@@ -1,7 +1,9 @@
 (turn-a-hooks-based-charm-into-an-ops-charm)=
 # How to turn a hooks-based charm into an ops charm
 
+<!-- UPDATE LINKS:
 > See first: [`juju` | Charm taxonomy]()
+-->
 
 Suppose you have a hooks-based charm and you decide to rewrite it using the Ops framework in Python.
 
@@ -24,7 +26,7 @@ We start by looking at the charm we intend to translate; as an example, we will
 
 From the charm root directory we see: 
 
-```bash
+```text
 $ tree .
 .
 ├── charmcraft.yaml