docs: fill out remaining external link placeholders (#1564)

All the remaining "UPDATE LINKS" notes in the docs are replaced with actual links to the external Juju/Charmcraft docs. Also changes the "product page" to be `juju.is` rather than `juju.is/docs/sdk` as the latter is going away (`juju.is` was recommended by @tmihoc). (These changes were previously in [a commit in another PR](tmihoc@54dca52) but got lost when changes were forced - it seemed cleanest to break them out into a separate PR).
canonical · Feb 11, 2025 · 0b23b6f · 0b23b6f
1 parent 73419d5
commit 0b23b6f
Show file tree

Hide file tree

Showing 5 changed files with 13 additions and 40 deletions.
diff --git a/docs/custom_conf.py b/docs/custom_conf.py
@@ -109,7 +109,7 @@
     # For example: "ubuntu.com/lxd" or "microcloud.is"
     # If there is no product website, edit the header template to remove the
     # link (see the readme for instructions).
-    'product_page': 'juju.is/docs/sdk',
+    'product_page': 'juju.is',
     # Add your product tag (the orange part of your logo, will be used in the
     # header) to ".sphinx/_static" and change the path here (start with "_static")
     # (default is the circle of friends)
@@ -298,8 +298,8 @@
 # that should be linked to in this documentation.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
-    'juju': ('https://canonical-juju.readthedocs-hosted.com/en/latest/', None),
-    'charmcraft': ('https://canonical-charmcraft.readthedocs-hosted.com/en/latest/', None),
+    'juju': ('https://canonical-juju.readthedocs-hosted.com/en/latest', None),
+    'charmcraft': ('https://canonical-charmcraft.readthedocs-hosted.com/en/latest', None),
 }
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/explanation/storedstate-uses-limitations.md b/docs/explanation/storedstate-uses-limitations.md
@@ -7,9 +7,7 @@
 
 This is an explanatory doc covering how charm authors might track local state in a Juju unit. We'll cover the `ops` concept of [](ops.StoredState), along with some differences in how it works between machine charms and Kubernetes charms. We'll talk about Peer Relations as an alternative for storing some kinds of information, and also talk about how charm authors probably should avoid recording state when they can avoid doing so.
 
-<!-- UPDATE LINKS
-"Peer Relations", above
--->
+> See more: {external+juju:ref}`Peer Relations <manage-relations>`
 
 ## A trivial example
 
@@ -107,14 +105,10 @@ def some_event_handler(event):
 
 In the other cases where state is needed, authors ideally want to relate a charm to a database, attach storage (see Juju storage), or simply be opinionated, and hard code the single "correct" state into the charm. (Perhaps `ExampleBlog` should always be run in `production` mode when deployed as a charm?)
 
-<!-- UPDATE LINKS
-"Juju Storage" above
--->
+> See more: {external+juju:ref}`Juju Storage <manage-storage>`
 
 In the cases where it is important to share some lightweight configuration data between units of an application, charm author's should look into peer relations. And in the cases where data must be written to a container's local file system (Canonical's Kubeflow bundle, for example, must do this, because the sheer number of services mean that we run into limitations on attached storage in the underlying cloud), authors should do so mindfully, with an understanding of the pitfalls involved.
 
-<!-- UPDATE LINKS
-"peer relations", above
--->
+> See more: {external+juju:ref}`Peer Relations <manage-relations>`
 
 In sum: use state mindfully, with well chosen tools, only when necessary.
diff --git a/docs/howto/get-started-with-charm-testing.md b/docs/howto/get-started-with-charm-testing.md
@@ -77,10 +77,6 @@ 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
 
 A 'live', deployed Juju application will have access to all the inputs we discussed above, including environment variables, host system access, and more. Unit tests will typically want to mock all that and focus on mapping inputs to expected outputs. Any combination of the input sources we mentioned above can result in any combination of operations. A few examples of increasing complexity of scenarios we may want to unit test:

diff --git a/docs/howto/manage-stored-state.md b/docs/howto/manage-stored-state.md
@@ -120,18 +120,14 @@ store the data in the relation databag.
 
 #### Define a peer relation
 
-Update the `charmcraft.yaml` file to add a `peers` block, as below:
+Update the {external+charmcraft:ref}`charmcraft.yaml file <charmcraft-yaml-file>` to add a `peers` block, as below:
 
 ```yaml
 peers:
   charm-peer:
     interface: my_charm_peers
 ```
 
-<!-- UPDATE LINKS
-> Read more: [File ‘charmcraft.yaml`]()
--->
-
 #### Set and get data from the peer relation databag
 
 In your `src/charm.py` file, set and get the data from the peer relation

diff --git a/docs/howto/write-integration-tests-for-a-charm.md b/docs/howto/write-integration-tests-for-a-charm.md
@@ -19,9 +19,7 @@ The instructions all use the Juju `python-libjuju` client, either through the `p
 
 In order to run integrations tests you will need to have your environment set up with `tox` installed.
 
-<!-- UPDATE LINKS
-> See more: {ref}`How to set up your development environment <set-up-your-development-environment>`
--->
+> See more: {external+juju:ref}`How to set up your development environment <manage-your-deployment-environment>`
 
 ## Prepare the `tox.ini` configuration file
 
@@ -175,9 +173,7 @@ async def test_config_changed(ops_test: OpsTest):
 
 ### Test an action
 
-<!-- UPDATE LINKS
-> See also: [Action]()
--->
+> See also: {external+juju:ref}`Action <action>`
 
 You can execute an action on a unit and get its results. 
 
@@ -214,11 +210,9 @@ How you can connect to a private or public address is dependent on your configur
 
 > Example implementations: [mongodb-k8s-operator](https://github.com/canonical/mongodb-k8s-operator/blob/8b9ebbee3f225ca98175c25781f1936dc4a62a7d/tests/integration/metrics_tests/test_metrics.py#L33), [tempo-k8s-operator](https://github.com/canonical/tempo-k8s-operator/blob/78a1143d99af99a1a56fe9ff82b1a3563e4fd2f7/tests/integration/test_integration.py#L69), [synapse](https://github.com/canonical/synapse-operator/blob/eb44f4959a00040f08b98470f8b17cae4cc616da/tests/integration/conftest.py#L170)
 
-<!-- UPDATE LINKS:
 > See more: 
-> - [Charm development best practices > Fetching network information]()
-> - [`juju` CLI commands > juju expose]()
--->
+> - {external+juju:ref}`Charm development best practices > Fetching network information <charm-development-best-practices>`
+> - {external+juju:ref}`juju CLI commands > juju expose <command-juju-expose>`
 
 ### Run a subprocess command within Juju context
 
@@ -280,15 +274,12 @@ Using the new alias, you can switch context to the new created model, similar to
 
 > Example implementations: [`charm-kubernetes-autoscaler`](https://github.com/charmed-kubernetes/charm-kubernetes-autoscaler/blob/8f4ddf5d66802ade73ed3aab2bb8d09fd9e4d63a/tests/integration/test_kubernetes_autoscaler.py#L31)
 
-<!-- UPDATE LINKS:
 > See more: 
-> - [Juju offers]()
-> - [How to manage clouds]()
+> - {external+juju:ref}`Juju offers <manage-offers>`
+> - {external+juju:ref}`How to manage clouds <manage-clouds>`
 > - [pytest-operator | track_model](https://github.com/charmed-kubernetes/pytest-operator/blob/ab50fc20320d3ea3d8a37495f92a004531a4023f/pytest_operator/plugin.py#L720)
 > - [pytest-operator | model_context](https://github.com/charmed-kubernetes/pytest-operator/blob/ab50fc20320d3ea3d8a37495f92a004531a4023f/pytest_operator/plugin.py#L480)
 > - [pytest-operator | forget_model](https://github.com/charmed-kubernetes/pytest-operator/blob/ab50fc20320d3ea3d8a37495f92a004531a4023f/pytest_operator/plugin.py#L812)
--->
-
 
 ### Deploy a bundle
 
@@ -377,10 +368,6 @@ There are different ways of specifying a subset of tests to run using `pytest`.
 tox -e integration -- tests/integration/test_charm.py -k "not test_one"
 ```
 
-<!-- UPDATE LINKS:
-> Example implementations: [`mysql-k8s-operator`]()
--->
-
 > See more: 
 > - [`pytest-operator` | `skip_if_deployed`](https://github.com/charmed-kubernetes/pytest-operator/blob/ab50fc20320d3ea3d8a37495f92a004531a4023f/pytest_operator/plugin.py#L139)
 > - [`pytest | How to invoke pytest`](https://docs.pytest.org/en/7.1.x/how-to/usage.html)