docs: fix links that pointed to earlier Juju docs #1575
Conversation
| @@ -136,7 +136,6 @@ It is in our interest to move the handler logic for each `/hooks/<hook_name>` to | |||
| - We can avoid code duplication by accessing shared data via the CharmBase interface provided through `self`. | |||
| - The code is all in one place, easier to maintain. | |||
| - We automatically have one Python object we can test, instead of going back and forth between Bash scripts and Python wrappers. | |||
| - We can use [the awesome testing Harness](https://juju.is/docs/sdk/testing). | |||
There was a problem hiding this comment.
My reasoning for this change: The preceding bullet already mentions testing. And Harness is not considered so awesome any more 💔
There was a problem hiding this comment.
I think it's fine to remove, but you could swap out Scenario for Harness (except you'd need to say "unit testing framework" or some other generic name) and it would still be true.
| To add a configuration layer, call [`Container.add_layer`](ops.Container.add_layer) with a label for the layer, and the layer's contents as a YAML string, Python dict, or [`pebble.Layer`](#ops.pebble.Layer) object. | ||
| To add a configuration layer, call [`Container.add_layer`](ops.Container.add_layer) with a label for the layer, and the layer's contents as a YAML string, Python dict, or [`pebble.Layer`](ops.pebble.Layer) object. |
There was a problem hiding this comment.
This change is out of scope of this PR, but it's the only instance that needs adjusting for consistency, so I'm including it here.
| Juju automatically picks up logs from charm code that uses the Python [logging facility](https://docs.python.org/3/library/logging.html), so we can use the Juju [`debug-log` command](https://juju.is/docs/juju/juju-debug-log) to display logs for a model. Note that it shows logs from the charm code (charm container), but not the workload container. Read ["Use `juju debug-log`"](https://juju.is/docs/sdk/get-logs-from-a-kubernetes-charm#heading--use-juju-debug-log) for more information. | ||
| Juju automatically picks up logs from charm code that uses the Python [logging facility](https://docs.python.org/3/library/logging.html), so we can use the Juju [`debug-log` command](inv:juju:std:label#command-juju-debug-log) to display logs for a model. Note that it shows logs from the charm code (charm container), but not the workload container. |
There was a problem hiding this comment.
I removed the link to https://juju.is/docs/sdk/get-logs-from-a-kubernetes-charm#heading--use-juju-debug-log because I can't find where this info has ended up. @tmihoc do you know whether we still have it somewhere?
There was a problem hiding this comment.
I'm not sure if it's the same content, but I think we should be linking here: https://canonical-juju.readthedocs-hosted.com/en/latest/user/howto/manage-logs/
Also: we should make this a See also: rather than having it in the paragraph.
| - shell commands against [the `juju` cli](https://juju.is/docs/olm/juju-cli-commands) | ||
| - shell commands against [the `juju` CLI](inv:juju:std:label#list-of-juju-cli-commands) |
There was a problem hiding this comment.
I'm using the MyST format for the intersphinx link to allow backticks in the link title.
| > See also: {ref}`holistic-vs-delta-charms` | ||
| > See also: [](/explanation/holistic-vs-delta-charms) |
There was a problem hiding this comment.
This change is out of scope of this PR, but I'm updating another instance elsewhere, so I'm using the same format here.
| <!-- | ||
| Before writing the code to start your workload, recall the [Lifecycle events](https://juju.is/docs/sdk/events) section, and note that when the `start` event is emitted, charm authors should ensure their workloads are configured to "persist in a started state without further intervention from Juju or an administrator". | ||
| --> |
There was a problem hiding this comment.
I'm not sure why this is commented out, but might as well remove it.
There was a problem hiding this comment.
It was common in Discourse for people to leave old chunks of content commented out. I'm not sure why, or if the intention was to include it again in the future, or something else. The history could always be examined via the edit tracking, so it shouldn't have been for that.
I've also taken the approach of removing it whenever I'm editing a file that has it (after checking that there isn't value to be added back in).
| @@ -25,7 +25,7 @@ def _on_leader_elected(self, event: ops.LeaderElectedEvent): | |||
| To have the leader notify other units about leadership changes, change data in a peer relation. | |||
|
|
|||
| > See more: [Peer Relations](https://juju.is/docs/juju/relation#heading--peer) | |||
| > See more: {external+juju:ref}`Juju | Peer relations <relation>` | |||
There was a problem hiding this comment.
This goes to relations in general rather than peer relations. I think that's fine, but maybe the link text should just say "Relation"?
| > See more: {external+juju:ref}`Juju | Peer relations <relation>` | |
| > See more: {external+juju:ref}`Juju | Relation <relation>` |
| Juju automatically picks up logs from charm code that uses the Python [logging facility](https://docs.python.org/3/library/logging.html), so we can use the Juju [`debug-log` command](https://juju.is/docs/juju/juju-debug-log) to display logs for a model. Note that it shows logs from the charm code (charm container), but not the workload container. Read ["Use `juju debug-log`"](https://juju.is/docs/sdk/get-logs-from-a-kubernetes-charm#heading--use-juju-debug-log) for more information. | ||
| Juju automatically picks up logs from charm code that uses the Python [logging facility](https://docs.python.org/3/library/logging.html), so we can use the Juju [`debug-log` command](inv:juju:std:label#command-juju-debug-log) to display logs for a model. Note that it shows logs from the charm code (charm container), but not the workload container. |
There was a problem hiding this comment.
I'm not sure if it's the same content, but I think we should be linking here: https://canonical-juju.readthedocs-hosted.com/en/latest/user/howto/manage-logs/
Also: we should make this a See also: rather than having it in the paragraph.
| <!-- | ||
| Before writing the code to start your workload, recall the [Lifecycle events](https://juju.is/docs/sdk/events) section, and note that when the `start` event is emitted, charm authors should ensure their workloads are configured to "persist in a started state without further intervention from Juju or an administrator". | ||
| --> |
There was a problem hiding this comment.
It was common in Discourse for people to leave old chunks of content commented out. I'm not sure why, or if the intention was to include it again in the future, or something else. The history could always be examined via the edit tracking, so it shouldn't have been for that.
I've also taken the approach of removing it whenever I'm editing a file that has it (after checking that there isn't value to be added back in).
| @@ -136,7 +136,6 @@ It is in our interest to move the handler logic for each `/hooks/<hook_name>` to | |||
| - We can avoid code duplication by accessing shared data via the CharmBase interface provided through `self`. | |||
| - The code is all in one place, easier to maintain. | |||
| - We automatically have one Python object we can test, instead of going back and forth between Bash scripts and Python wrappers. | |||
| - We can use [the awesome testing Harness](https://juju.is/docs/sdk/testing). | |||
There was a problem hiding this comment.
I think it's fine to remove, but you could swap out Scenario for Harness (except you'd need to say "unit testing framework" or some other generic name) and it would still be true.
| @@ -206,7 +205,7 @@ That allows us to fetch the Relation wherever we need it and access its contents | |||
| ) | |||
| ``` | |||
|
|
|||
| Note how `relation.data` provides an interface to the relation databag (more on that [here](https://juju.is/docs/sdk/relations#heading--relation-data)) and we need to select which part of that bag to access by passing an `ops.model.Unit` instance. | |||
| Note how `relation.data` provides an interface to the relation databag (see [](ops.Relation.data)) and we need to select which part of that bag to access by passing an `ops.model.Unit` instance. | |||
There was a problem hiding this comment.
This was going to a Juju reference page previously rather than to the ops API reference. I can't figure out where that is now: @tmihoc did it get removed?
If it doesn't exist any more, I think maybe linking to the section in the relation how-to might be better here?
| @@ -522,7 +522,7 @@ Congratulations, your charm user can view the version of the workload deployed f | |||
|
|
|||
| ## Tear things down | |||
|
|
|||
| > See [Juju | Tear down your development environment automatically](https://juju.is/docs/juju/set-up--tear-down-your-test-environment#tear-down-automatically) | |||
| > See the automatic teardown instructions in {external+juju:ref}`Juju | Manage your deployment environment <manage-your-deployment-environment>`. | |||
There was a problem hiding this comment.
Is it possible to link directly to the tear down section? If not that's fine.
There was a problem hiding this comment.
Yeah, I agree that would be better. I've asked Dora about adding a target so that we can directly link there.
There was a problem hiding this comment.
@dwilding Added it in this PR: https://github.com/juju/juju/pull/18911/files
I did the same with the preview build on rtd, by the way. So between us we have good coverage :) |
There's a preview build!? |
The preview build is here: https://ops--1575.org.readthedocs.build/en/1575/. You can find it by clicking Details for the check called "docs/readthedocs.org:ops". Sorry, I should have pasted it into the PR description (I usually do that). |
This PR replaces links to https://juju.is/docs/ by internal cross-references to other Ops pages or intersphinx cross-references to Juju pages (as appropriate).
Not included in this PR
The link in https://ops.readthedocs.io/en/latest/howto/get-started-with-charm-testing.html#charmcraft-profiles that should point to the Charmcraft docs. I'll follow up with a separate PR after docs: update 12-factor tutorials charmcraft#2085 gets merged into Charmcraft.
Links in the code samples of the Kubernetes tutorial (for example, in Create a minimal Kubernetes charm). I think it would be better to tackle these separately when improving the tutorial - @tonyandrewmeyer what do you think?