docs: set up intersphinx and add links

[tmihoc]

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 ).

[tonyandrewmeyer]

There are a few links to sections in charmcraft docs that I think are not exported:

docs/howto/manage-configurations.md:3: WARNING: external std:ref reference target not found: manage-configurations [ref.ref]
docs/howto/manage-relations.md:3: WARNING: external std:ref reference target not found: manage-relations [ref.ref]
docs/howto/manage-secrets.md:3: WARNING: external std:ref reference target not found: manage-secrets [ref.ref]
docs/howto/manage-storage.md:3: WARNING: external std:ref reference target not found: manage-storage [ref.ref]
docs/tutorial/write-your-first-machine-charm.md:188: WARNING: external std:ref reference target not found: pack-a-charm [ref.ref]

For example:

$ intersphinx list https://canonical-charmcraft.readthedocs-hosted.com/en/stable --includes secret
$ intersphinx list https://canonical-charmcraft.readthedocs-hosted.com/en/stable --includes configurations
$ 

For these to work, I think we need to get the charmcraft docs to explicitly provide reference anchors for these.

[benhoyt]

Nice work -- thanks Dora (and Tony). Just one question about "See first" reading awkwardly (to me).

[benhoyt]

"See first" reads awkwardly to me. What about "Read first"?

[tmihoc]

"See first" reads awkwardly to me. What about "Read first"?

Open to either, but the current verb we use everywhere else is "See": "See also", "See more", "See first", "See next". Do you find all of those awkward or just this one?

[benhoyt]

Just this one. "See also" and "See more" are common and clear. But "See first" and "See next" I find unusual and unclear. I'm guessing "see first" means "read this first"? It's just not a phrase that I've heard before and it gives me pause. And "See next" (if I'm understanding what you mean by it) seems too close to "See also" -- more commonly for that I've seen just "Next", or maybe "Next up".

[tmihoc]

So, the problem is as follows. In any doc set there's a need to cross-reference. In the past we used to cross-reference without any system. Over the past few years I've been deliberate about keeping in-line references only between reference (=definition) docs. For everything else I have an out-of-line pattern with the phrases "See also", for 'lateral' kinds of links from, e.g., Manage models to the reference doc defining the notion of 'model', and "See more" for 'zoom-in' type links from, e.g., Add a model to details about the juju add-model command. This pattern isn't necessarily something you find anywhere else, but it's a pattern I've gotten good feedback on and that seems to be working exactly as intended.

Now, with the move to federated docs and the fact that for certain entities we have stories that start in Juju docs, are continued in Charmcraft docs, and then finished in Ops docs, it feels necessary to expand the "See ___" system in a way that would give people a clue about how the order in which the stories connect. E.g., the Manage configurations story in Charmcraft should tell people to look at Juju first and at Ops next.

If "first" and "next" don't work for you, I'm open to suggestion. I would emphasize however that the "See ___" system has worked well for now, so I'd prefer sticking with "See ___", and also that "Next up" doesn't really capture the intended meaning here.

On a different note: We should be able to launch the new docs next week (the web team is almost done with the entrypoint page). As such, I believe it's important to ensure that the various doc sets are properly connected. This PR achieves that. May I suggest we merge it as is? On my part I promise to keep thinking about this, to discuss it with the other TAs, and to also proactively seek user feedback on it.

[benhoyt]

Yes, it's totally fine to merge this now (and keep thinking about it). I guess I think it's not clear on its own, but in context it kinda works.

[tmihoc]

There are a few links to sections in charmcraft docs that I think are not exported:

For these to work, I think we need to get the charmcraft docs to explicitly provide reference anchors for these.

I'm creating them in a parallel PR. (It's arguably one of the cons of using intersphinx; makes me reconsider the choice a little bit).

[tonyandrewmeyer]

I'm creating them in a parallel PR.

Ah, I have one open already, linked above: canonical/charmcraft#2129

Feel free to do a different one if there's a better naming scheme or I've missed some or whatever and I can close mine.

[tmihoc]

I'm creating them in a parallel PR.

Ah, I have one open already, linked above: canonical/charmcraft#2129

Feel free to do a different one if there's a better naming scheme or I've missed some or whatever and I can close mine.

My PR is already in review: https://github.com/canonical/charmcraft/pull/2128/files#

Sorry, i should have mentioned this upfront.

[benhoyt]

We're happy to merge this, but we'd like to wait till the anchors in Charmcraft PR canonical/charmcraft#2128 are merged, which should fix the docs build.

[tonyandrewmeyer]

Review via reading all looks good.

Manually tested a couple of links to Juju and to Charmcraft and they work, and all the build errors are gone, so all of the others should also be fine.

@tmihoc I've made two changes (and fixed a couple of typos):

• The charmcraft intersphinx links to latest instead of stable. latest has the new anchors and stable doesn't, so this is at least a short-term change to get this PR merged. I'm not sure if they'll get backported in charmcraft or not. However, we're linking to Juju latest, and (a) I think probably we should be consistent, and (b) I think probably linking to latest makes most sense, as we might be referring to new Juju/Charmcraft content, and if someone needs to look back they can do that easily enough after following the link.
• There's one Juju link that doesn't seem to exist. I think it's meant to be to this page - but the anchor isn't there, and I can't find a Juju PR that would add it. I've just removed it from the ops docs for now and added a TODO so that this one can get merged. If you can either confirm that's the right place or add/merge a PR to Juju to get the machine-charm anchor there, I'm happy to handle opening a follow-up ops PR to put the link back.