Support for RTD documentation on Charmhub

announcements and community
1

Hi everyone!

TLDR: Integrated RTD docs support in charmhub is live, replace docs: in metadata.yaml to your RTD link and get this button in your page.

image

We’ve been carefully gathering feedback to understand main pains of being a charm maintainer over the last 2 cycles and I want to share a first visible improvement to the charm documentation part of the experience.

Using discourse for documentation has been hard because of:

  • No versioning support
  • Difficult information architecture
  • Minimal automation and templating
  • …

Due to this we’ve seen more and more of you move your documentation to RTD and using the description in various ways to direct people to it. To make this more integrated and consistent we’re now supporting a way to have integrated link to the documentation if it’s hosted anywhere else but discourse.

image
image1966×1194 210 KB
Live example

To enable this, update the docs: field in your metadata.yaml with your RTD link. When that is done, the content in Description tab will be rendering the readme and the outlink to the docs.

While this is a fairly simple fix, we’d like to hear if:

  • There any concerns with this approach?
  • Any other links we should keep in mind?
  • What would you like to see done differently? Why?
3 Likes
2

Thank you very much for adding such a great feature. I have a question about how the feature works. The post above says:

the content in Description tab will be rendering the readme

But in the Live etcd example provided (and in the latest edge revision too), I see a different situation. As far as I can see, it renders not the README file content, but the content of the description field from the metadata.yaml file, which is the default behaviour for when we have no documentation link.

Can you clarify, what is intended behaviour here?

I’d love to see the README file being rendered, so we can have a more complex description with some code blocks and other types of content. Additionally, using a README file as the source for the Description tab render, reduces the number of documentation-related places that we need to maintain.

3

In case people aren’t aware: the best way to do this is to change the documentation field in the links section of your charmcraft.yaml file. Charmcraft will then take care of populating the metadata.yaml file inside of the charm at packing time.