How to document your charm library
You’ve created your charm library. It is now time to document it. Libraries have 3 types of documentation sections: the metadata, the header of the file, and the Python docstring. This document shows how to use each.
charmcraft create-lib automatically generates inside the
<libname>.py the following metadata fields:
# Do not change LIBID = "abcdef12345" # Unique ID that refers to the library forever LIBAPI = 3 # API version for non-backwards compatibility evolution LIBPATCH = 2 # A patch version for all non-breaking changes def function(): return "foo" class Example: def __init__(self, foo, bar): self.foo = foo self.bar = bar def info(self, add): return add + self.foo
LIBID is a unique identifier for the library across the entire universe of charms that is assigned by Charmhub to this particular library automatically at library creation time. It enables Charmhub and
charmcraft to track the library uniquely even if the charm or the library are renamed, which allows updates to warn and guide users through the process. Make sure to never change it.
LIBPATCH are set to an initial state (
1 correspondingly), which is fine for now, but in general note that LIBAPI must match the major version in the import path and LIBPATCH must match the current patch version (needs to be updated when changing).
The header of the file is a Python comment at the top of your library written using the triple quote:
"""Like this """. It supports Markdown following the CommonMark specification.
Use the header to describe the library.
The Python docstring is used to describe the functions and classes that the library provides. It supports the Google Python Docstring format.
Use Python docstrings to explain each function.
def function(): """This sentence is a summary of the function. This section gives more details about the function and what it does. In this case the function returns foo. Returns: A string containing "foo" """ return "foo" class Example: """A one sentence summary of the class. This section gives more details about the class and what it does. Arguments: foo (int): the argument foo bar (str): the argument bar Attributes: foo (int): the attribute foo bar (str): the attribute bar """ def __init__(self, foo, bar): self.foo = foo self.bar = bar def info(self, add=1): """Return foo plus add. This function adds add to foo Arguments: add (int, optional): The number to add to foo. Defaults to 1. Returns: self.foo plus add """ return add + self.foo
Last updated 4 months ago.