Document your library

Introduction

Duration: 00:10

One of the most distinct features of a charm is the way it can readily relate to another charm. For this interface, there is one charm that will provide information in a specific way, and a charm that will consume information in a matching way to connect and work together. To ensure that the charm interface is a perfect pairing, the operator framework tooling and the store support a mechanism to publish and reuse this logic in a form of simple files, that we’ll call libraries. This tutorial will show you how to structure and publish your library so it can be easily shared and consumed.

What you’ll learn

  • The standard that Charmhub uses to document and display libraries
  • How to publish and access your library on charmhub.io

What you’ll need

The structure

Duration: 02:00

Libraries have 2 sections of documentation:

  • The header of the file: this is a python comment using the triple quote: """Like this """. This section describes the library and supports Markdown following the CommonMark specification.
  • The Python docstring: these docstrings are used to describe the functions and classes that the library provides. The docstring supports the Google Python Docstring format.

Example

Duration: 02:00

Inside a charm there is a specific directory_, _under which there are subdirectories with this naming convention:

$CHARMDIR/lib/charms/<charm>/v<API>/<libname>.py

$CHARMDIR is the project’s root (contains src/, hooks/, etc), and the <charm> placeholder represents the charm responsible for the library named as <libname>.py with API version <API>.

Inside <libname>.py the following fields must necessarily be defined:

Default generated by the command: charmcraft create-lib

# 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 

The header

Describe this class by adding a section at the top of the library:

 # My library

This library was made as while following **a tutorial**.

You can find more information on [the Charmhub website]([https://charmhub.io](https://charmhub.io)).

Note that the section supports markdown.

The docstring

Explain each function using Google Python Docstring.

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

Publish and share

Duration: 01:00

In a terminal, go into the charm project and run the command: charmcraft publish-lib LIBRARY_CLASS, where LIBRARY_CLASS is the python module path of the library.

To share it with developers:

  • Access your charm page on charmhub.io.
  • Go on the library tab.
    image
  • You should see on the left navigation your library
  • Click on it
  • You can now share this URL with other charm developers

Wrapping up

Duration: 00:10

Libraries are a great way to help other authors to write charms that can relate to yours. Be sure to review your library to make sure it looks as intended and feel free to share the library URL with other charm developers.