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.

Contents:

The metadata

The command 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.

LIBAPI and LIBPATCH are set to an initial state (0 and 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

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 docstring

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 9 months ago.