docs: set up intersphinx and add links (#1546)

This PR sets up intersphinx for Juju and Charmcraft links and adds intersphinx-style links to Juju and Charmcraft in all the places we had bookmarked through UPDATE LINKS comments before (see #1516 ). --------- Co-authored-by: Tony Meyer <[email protected]>
canonical · Feb 4, 2025 · d63208d · d63208d
1 parent 427aaf3
commit d63208d
Show file tree

Hide file tree

Showing 15 changed files with 86 additions and 125 deletions.
diff --git a/docs/custom_conf.py b/docs/custom_conf.py
@@ -295,7 +295,11 @@
 
 # This config value contains the locations and names of other projects
 # that should be linked to in this documentation.
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+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),
+}
 
 # -- General configuration ---------------------------------------------------
 

diff --git a/docs/howto/manage-actions.md b/docs/howto/manage-actions.md
@@ -1,9 +1,6 @@
 (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]()
--->
+> See first: {external+juju:ref}`Juju | Charm <action>`, {external+juju:ref}`Juju | Manage actions <manage-actions>`, {external+charmcraft:ref}`Charmcraft | Manage actions <manage-actions>`
 
 ## Implement the feature
 

diff --git a/docs/howto/manage-configurations.md b/docs/howto/manage-configurations.md
@@ -1,9 +1,6 @@
 (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]()
--->
+> See first: {external+juju:ref}`Juju | <application-configuration>`, {external+juju:ref}`Juju | Manage applications > Configure <configure-an-application>`, {external+charmcraft:ref}`Charmcraft | Manage configurations <manage-configurations>`
 
 
 ## Implement the feature

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

diff --git a/docs/howto/manage-libraries.md b/docs/howto/manage-libraries.md
@@ -1,9 +1,8 @@
 (manage-libraries)=
 # Manage libraries
+> See first: {external+charmcraft:ref}`Charmcraft | Manage libraries <manage-libraries>`
+
 
-<!-- UPDATE LINKS:
-> See first: [`juju` | Library](), [`charmcraft` | Manage libraries]()
--->
 ## Write a library
 
 When you're writing libraries, instead of callbacks, you can use custom events; that'll result in a more `ops`-native-feeling API. A custom event is, from a technical standpoint, an EventBase subclass that can be emitted at any point throughout the charm's lifecycle. These events are therefore totally unknown to Juju. They are essentially charm-internal, and can be useful to abstract certain conditional workflows and wrap the toplevel Juju event so it can be observed independently.
@@ -221,10 +220,6 @@ def test_my_object_data(context, endpoint, n_relations):
 
 Fetch the library.
 
-<!-- UPDATE LINKS:
-> See more: [`charmcraft` | Manage libraries]()
--->
-
 In your `src/charm.py`, observe the custom events it puts at your disposal. For example, a database library may have provided a  `database_relation_ready` event -- a high-level wrapper around the relevant `juju` relation events -- so you use it to manage the database integration in your charm as below:
 
 ```python

diff --git a/docs/howto/manage-logs.md b/docs/howto/manage-logs.md
@@ -1,9 +1,7 @@
 (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)
--->
+> See first: {external+juju:ref}`Juju | Log <log>`, {external+juju:ref}`Juju | Manage logs <manage-logs>`
 
 <!--
 > 

diff --git a/docs/howto/manage-relations.md b/docs/howto/manage-relations.md
@@ -1,12 +1,9 @@
 (manage-relations)=
 # How to manage relations
+> See first: {external+juju:ref}`Juju | Relation <relation>`, {external+juju:ref}`Juju | Manage relations <manage-relations>`, {external+charmcraft:ref}`Charmcraft | Manage relations <manage-relations>`
 
 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
 
 ### Declare the relation endpoint

diff --git a/docs/howto/manage-resources.md b/docs/howto/manage-resources.md
@@ -1,9 +1,7 @@
 (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]()
--->
+> See also: {external+juju:ref}`Juju | Charm resource <charm-resource>`, {external+juju:ref}`Juju | Manage charm resources <manage-charm-resources>`, {external+charmcraft:ref}`Charmcraft | Manage resources <manage-resources>`
 
 ## Implement the feature
 

diff --git a/docs/howto/manage-secrets.md b/docs/howto/manage-secrets.md
@@ -1,9 +1,6 @@
 (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]()
--->
+> See first: {external+juju:ref}`Juju | Secret <secret>`, {external+juju:ref}`Juju | Manage secrets <manage-secrets>`, {external+charmcraft:ref}`Charmcraft | Manage secrets <manage-secrets>`
 
 > Added in `Juju 3.0.2`
 

diff --git a/docs/howto/manage-storage.md b/docs/howto/manage-storage.md
@@ -1,9 +1,6 @@
 (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]()
--->
+> See first: {external+juju:ref}`Juju | Storage <storage>`, {external+juju:ref}`Juju | Manage storage <manage-storage>`, {external+charmcraft:ref}`Charmcraft | Manage storage <manage-storage>`
 
 ## Implement the feature
 

diff --git a/docs/howto/manage-stored-state.md b/docs/howto/manage-stored-state.md
@@ -1,7 +1,7 @@
 (manage-stored-state)=
 # How to manage stored state
 
-> See first: [](storedstate-uses-limitations)
+> See first: {ref}`storedstate-uses-limitations`
 
 Data stored on a charm instance will not persist beyond the current Juju event,
 because a new charm instance is created to handle each event. In general, charms

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,9 +1,6 @@
 (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]()
--->
+> See first: {external+juju:ref}`Juju | Charm taxonomy <charm-taxonomy>`
 
 Suppose you have a hooks-based charm and you decide to rewrite it using the Ops framework in Python.
 

diff --git a/docs/howto/write-integration-tests-for-a-charm.md b/docs/howto/write-integration-tests-for-a-charm.md
@@ -13,7 +13,7 @@ Integration testing is only one part of a comprehensive testing strategy. See {r
 
 The instructions all use the Juju `python-libjuju` client, either through the `pytest-operator` library or directly.
 
-> See more: [`python-libjuju`](https://github.com/charmed-kubernetes/pytest-operator), {ref}`pytest-operator`
+> See more: [`python-libjuju`](https://pythonlibjuju.readthedocs.io/en/latest/), {ref}`pytest-operator`
 
 ## Prepare your environment
 
@@ -100,9 +100,7 @@ As an alternative to `wait_for_idle`, you can explicitly block until the applica
 
 ### Deploy your charm with resources
 
-<!-- UPDATE LINKS
-> See also: [Resource (Charm)](https://juju.is/docs/juju/charm-resource)
--->
+> See first: `manage-resources`
 
 A charm can require `file` or `oci-image` `resources` to work, that can be provided to `ops_test.model.deploy`. In Charmhub, resources have revision numbers. For file resources already stored in Charmhub, you can use `ops_test.download_resources`:
 
@@ -156,10 +154,7 @@ async def test_my_integration(ops_test: OpsTest):
 
 ### Test a configuration
 
-<!-- UPDATE LINKS
-
-> See also: [Configuration]()
--->
+> See first: {ref}`manage-configurations`
 
 You can set a configuration option in your application and check its results. 
 

diff --git a/...rom-zero-to-hero-write-your-first-kubernetes-charm/preserve-your-charms-data.md b/...rom-zero-to-hero-write-your-first-kubernetes-charm/preserve-your-charms-data.md
@@ -3,7 +3,7 @@
 
 > <small> {ref}`From Zero to Hero: Write your first Kubernetes charm <from-zero-to-hero-write-your-first-kubernetes-charm>` > Preserve your charm's data </small>
 >
-> **See previous: {ref}`Integrate your charm with PostgreSQL <integrate-your-charm-with-postgresql>`** 
+> **See previous: {ref}`Integrate your charm with PostgreSQL <integrate-your-charm-with-postgresql>`**
 
 
 ````{important}
@@ -20,7 +20,7 @@ git checkout -b  05_preserve_charm_data
 ````
 
 
-Charms are stateless applications. That is, they are reinitialised for every event and do not retain information from previous executions. This means that, if an accident occurs and the Kubernetes pod dies, you will also lose any information you may have collected. 
+Charms are stateless applications. That is, they are reinitialised for every event and do not retain information from previous executions. This means that, if an accident occurs and the Kubernetes pod dies, you will also lose any information you may have collected.
 
 In many cases that is not a problem. However, there are situations where it may be necessary to maintain information from previous runs and to retain the state of the application. As a charm author you should thus know how to preserve state.
 
@@ -30,35 +30,30 @@ First, you can use an Ops construct called `Stored State`. With this strategy yo
 
 > Read more: [](ops.StoredState), {ref}`StoredState: Uses, Limitations <storedstate-uses-limitations>`
 
-Second, you can make use of the Juju notion of 'peer relations'  and 'data bags'  and set up a peer relation data bag. This will help you store the information in the Juju's database backend. 
+Second, you can make use of the Juju notion of 'peer relations'  and 'data bags'  and set up a peer relation data bag. This will help you store the information in the Juju's database backend.
 
 
-<!-- UPDATE LINKS
-> Read more: [Peer relations](https://juju.is/docs/juju/relation#heading--peer)
--->
+> See more: {external+juju:ref}`Juju | Peer relation <peer-relation>`
 
 Third, when you have confidential data, you can use Juju secrets (from Juju 3.1 onwards).
 
-<!-- UPDATE LINKS
-> Read more: [Juju | Secret](https://juju.is/docs/juju/secret)
--->
+> See more: {external+juju:ref}`Juju | Secret <secret>`
 
 
 In this chapter we will adopt the second strategy, that is, we will store charm data in a peer relation databag. (We will explore the third strategy in a different scenario in the next chapter.)  We will illustrate this strategy with an artificial example where we save the counter of how many times the application pod has been restarted.
 
 ## Define a peer relation
 
-The first thing you need to do is define a peer relation. Update the `charmcraft.yaml` file to add a `peers` block before the `requires` block, as below (where `fastapi-peer` is a custom name for the peer relation and `fastapi_demo_peers` is a custom name for the peer relation interface): 
+The first thing you need to do is define a peer relation. Update the `charmcraft.yaml` file to add a `peers` block before the `requires` block, as below (where `fastapi-peer` is a custom name for the peer relation and `fastapi_demo_peers` is a custom name for the peer relation interface):
 
 ```yaml
 peers:
   fastapi-peer:
     interface: fastapi_demo_peers
 ```
 
-<!-- UPDATE LINKS
-> Read more: [File ‘charmcraft.yaml`]()
--->
+
+> See more: {external+charmcraft:ref}`Charmcraft | File charmcraft.yaml <charmcraft-yaml-file>`
 
 ## Set and get data from the peer relation databag