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.
There was a problem hiding this comment.
I think it's best to omit the link here, as it's not something we want the reader to start working through right away. I'm adding a small section towards the end of the doc to remind the reader that they should write tests, with a link to Get started with charm testing.
docs/howto/manage-logs.md
Outdated
| 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.
There was a problem hiding this comment.
I don't think Juju | How to manage logs addresses the point in such an explicit way. Anyway, I agree it's a more appropriate place to link to. Good idea about "see also" - I'm putting it in a "see more", to be consistent with the rest of the page.
There was a problem hiding this comment.
I'd use a `>See first: Juju | Manage logs'. I've done that for both Charmcraft and Ops. The idea being that we want people to be aware of what a thing looks like on the charm user end first, as that's likely to be the fastest way for them to catch up.
There was a problem hiding this comment.
Great point. I just realised that we already have a "see first" link to that page. I've updated the "see first" block to list the how-to link before the reference link.
There was a problem hiding this comment.
Oops, I just found the commit for this sitting in my editor. I thought I'd pushed it, but apparently not... I'll do a separate PR for it: #1584
docs/howto/manage-logs.md
Outdated
| 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.
| @@ -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.
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). |
|
Thanks everyone for your feedback! @tonyandrewmeyer I've addressed all the comments now - please could you review again when you get a chance? One thing to note: while updating the links to Set things up and Tear things down, I also made some formatting changes to smooth out the flow (to my eyes). These changes: 5f4828a |
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?