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
- A published charm
- A library ready to be documented
- The charmcraft snap
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.
- 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.