How to document charms
The most successful charms are those with the best documentation. It is essential that as a charm developer you empower administrators, and other developers in the community, to understand the purpose of your charm, its behaviours, failure modes and ideal deployment conditions.
The README is likely to be the first encounter that people have with your charm. The README should be end-user oriented, focusing on what the charm does. While it may be prudent to include snippets from the underlying application documentation, the focus should be on your charm.
As a general rule, your README should provide
- A quick getting started guide for a simple deployment
- Mandatory configuration steps for minimal deployment - such as required relationships
- Links to more detailed documentation (like a Discourse post - see below)
- Where applicable, links to the OCI image source
- Minimum requirements for a high availability deployment
- Links to complementary/supplementary charms
- Documentation for charm configuration options (if applicable)
- Documentation for charm actions (if applicable)
Your README should not include developer-specific instructions. Please include any detailed information on how to build, test and contribute to your charm as part of the Discourse/Charmhub docs outlined in the next section.
Charmhub makes it easy to publish and collaborate on documentation for your charm. Documentation pages are managed in the Charmhub Discourse, which means community members can comment on them and help improve them directly. To get started documenting your charm, you must have already published your charm, and have a basic understanding of Markdown.
Each charm has its own “Docs” page at
https://charmhub.io/<charm>/docs. The page structure allows for a navigation bar on the left hand side, with content displayed on the right. An example of this can be seen on the Mattermost charm page.
To get started documenting your charm, first create a new topic in the ‘charm’ category. That link should set you up with a new topic and a basic template. Here are some guidelines:
- Call your topic
<charm name> docs - index
- Tag your topic with the
docstag, and also with your charm name, for example:
- The body of this topic should contain the cover page and navigation, including a full list of document pages for your charm
- Each page of your documentation should be a new topic in Discourse
Below is a good cover page template that will help you setup your documentation with navigation and multiple pages (if you used the create topic link, this should be populated automatically):
The cover page of your docs. This should be some introductory text which will be displayed on the front page of the Docs tab for your charm. All the content above the 'Navigation' heading below is part of the cover page. # Navigation | Level | Path | Navlink | | ----- | -------- | ------------------------------- | | 1 | | [Overview](/t/topic-title/<ID>) | | 1 | install | [install](/t/topic-title/<ID>) | | 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) | | 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) | | 1 | topic | [install](/t/topic-title/<ID>) | | 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) | # Redirects [details=Mapping table] | Path | Location | | ---- | -------- | [/details]
Please note that permissions to post links on Discourse are dictated by a trust level. You may need to interact with the forum before you can create your cover page with multiple links.
If you need help creating your cover page, please get in touch with us on the Community Mattermost
All of the text above your
# Navigation header will appear on the cover page for your charm at
https://charmhub.io/<charm>/docs. You can use Markdown formatting here, including headings, images, lists and code snippets. This is a good place to include the main usage of your charm and any limitations.
The navigation section becomes essential as your documentation grows. To populate the navigation correctly, you must create a Markdown table with three columns, as shown below:
# Navigation | Level | Path | Navlink | | ----- | -------- | ------------------------------- | | 1 | | [Overview](/t/topic-title/<ID>) | | 1 | install | [install](/t/topic-title/<ID>) | | 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) | | 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) | | 1 | topic | [install](/t/topic-title/<ID>) | | 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) |
The three columns are explained below:
||Used to create a tree structure in the navigation. Level 1 corresponds to a top-level item in the navigation|
||This value will be used to transform any Discourse URL to a path in your charm docs. For example:
||This column specifies the link to the Discourse topic. This should be specified as a Markdown link
Redirects enable you to change the path to a specific doc at a later date should the need arise. Redirects are specified in a table, similar to the navigation section. The table must be in a section named
Redirects. An example is shown below:
# Redirects [details=Mapping table] | Path | Location | | -------------------------- | -------------------------- | | <charm name>/docs/old-path | <charm name>/docs/new-path | [/details]
When the above table is specified, anyone visiting
charmhub.io/<charm name>/docs/old-path would be automatically redirected to
You can create as many documentation pages as you like for your charm. Each page just requires a new topic. Each new topic should have the tags
<charm name>. Don’t forget to update your documentation cover page with a link to the topic, and you may want to add the new topic to the navigation too.
You do not need to specify a navigation or redirect section in additional pages, these will be automatically handled by the documentation index topic.
Linking charms and docs
Once you have created your documentation pages, you need to tell Charmhub which index page to use for your charm. You can do this by updating your charm’s
metadata.yaml, and then re-publishing it. The link belongs under the
docs key in the
metadata.yaml file like so:
# ... docs: https://discourse.charmhub.io/t/<charm name>-docs-index/9999 # ...
Now build and publish your charm with
charmcraft and your docs page should be live!
Last updated a month ago.