You've learned about the CircuitPython built-in modules and external libraries. You know that you can find the modules in CircuitPython, and the libraries in the Library Bundles. There are guides available that explain the basics of many of the modules and libraries. However, there's sometimes more capabilities than are necessarily showcased in the guides, and often more to learn about a module or library. So, where can you find more detailed information? That's when you want to look at the API documentation.
The entire CircuitPython project comes with extensive documentation available on Read the Docs. This includes both the CircuitPython core and the Adafruit CircuitPython libraries.
CircuitPython Core Documentation
The CircuitPython core documentation covers many of the details you might want to know about the CircuitPython core and related topics. It includes API and usage info, a design guide and information about porting CircuitPython to new boards, MicroPython info with relation to CircuitPython, and general information about the project.
The main page covers the basics including where to download CircuitPython, how to contribute, differences from MicroPython, information about the project structure, and a full table of contents for the rest of the documentation.
The list along the left side leads to more information about specific topics.
The first section is API and Usage. This is where you can find information about how to use individual built-in core modules, such as time and digitalio, details about the supported ports, suggestions for troubleshooting, and basic info and links to the library bundles. The Core Modules section also includes the Support Matrix, which is a table of which core modules are available on which boards.
The second section is Design and Porting Reference. It includes a design guide, architecture information, details on porting, and adding module support to other ports.
The third section is MicroPython Specific. It includes information on MicroPython and related libraries, and a glossary of terms.
The fourth and final section is About the Project. It includes further information including details on building, testing, and debugging CircuitPython, along with various other useful links including the Adafruit Community Code of Conduct.
Whether you're a seasoned pro or new to electronics and programming, you'll find a wealth of information to help you along your CircuitPython journey in the documentation!
CircuitPython Library Documentation
The Adafruit CircuitPython libraries are documented in a very similar fashion. Each library has its own page on Read the Docs. There is a comprehensive list available here. Otherwise, to view the documentation for a specific library, you can visit the GitHub repository for the library, and find the link in the README.
For the purposes of this page, the LED Animation library documentation will be featured. There are two links to the documentation in each library GitHub repo. The first one is the docs badge near the top of the README.
The second place is the Documentation section of the README. Scroll down to find it, and click on Read the Docs to get to the documentation.
Now that you know how to find it, it's time to take a look at what to expect.
The Introduction page is generated from the README, so it includes all the same info, such as PyPI installation instructions, a quick demo, and some build details. It also includes a full table of contents for the rest of the documentation (which is not part of the GitHub README). The page should look something like the following.
The left side contains links to the rest of the documentation, divided into three separate sections: Examples, API Reference, and Other Links.
Examples
The Examples section is a list of library examples. This list contains anywhere from a small selection to the full list of the examples available for the library.
This section will always contain at least one example - the simple test example.
The simple test example is usually a basic example designed to show your setup is working. It may require other libraries to run. Keep in mind, it's simple - it won't showcase a comprehensive use of all the library features.
The LED Animation simple test demonstrates the Blink animation.
In some cases, you'll find a longer list, that may include examples that explore other features in the library. The LED Animation documentation includes a series of examples, all of which are available in the library. These examples include demonstrations of both basic and more complex features. Simply click on the example that interests you to view the associated code.
You can view the rest of the examples by clicking through the list or scrolling down the page. These examples are fully working code. Which is to say, while they may rely on other libraries as well as the library for which you are viewing the documentation, they should not require modification to otherwise work.
API Reference
The API Reference section includes a list of the library functions and classes. The API (Application Programming Interface) of a library is the set of functions and classes the library provides. Essentially, the API defines how your program interfaces with the functions and classes that you call in your code to use the library.
There is always at least one list item included. Libraries for which the code is included in a single Python (.py) file, will only have one item. Libraries for which the code is multiple Python files in a directory (called subpackages) will have multiple items in this list. The LED Animation library has a series of subpackages, and therefore, multiple items in this list.
Click on the first item in the list to begin viewing the API Reference section.
When you click on an item in the API Reference section, you'll find details about the classes and functions in the library. In the case of only one item in this section, all the available functionality of the library will be contained within that first and only subsection. However, in the case of a library that has subpackages, each item will contain the features of the particular subpackage indicated by the link. The documentation will cover all of the available functions of the library, including more complex ones that may not interest you.
The first list item is the animation subpackage. If you scroll down, you'll begin to see the available features of animation. They are listed alphabetically. Each of these things can be called in your code. It includes the name and a description of the specific function you would call, and if any parameters are necessary, lists those with a description as well.
You can view the other subpackages by clicking the link on the left or scrolling down the page. You may be interested in something a little more practical. Here is an example. To use the LED Animation library Comet animation, you would run the following example.
# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
This example animates a jade comet that bounces from end to end of the strip.
For QT Py Haxpress and a NeoPixel strip. Update pixel_pin and pixel_num to match your wiring if
using a different board or form of NeoPixels.
This example will run on SAMD21 (M0) Express boards (such as Circuit Playground Express or QT Py
Haxpress), but not on SAMD21 non-Express boards (such as QT Py or Trinket).
"""
import board
import neopixel
from adafruit_led_animation.animation.comet import Comet
from adafruit_led_animation.color import JADE
# Update to match the pin connected to your NeoPixels
pixel_pin = board.A3
# Update to match the number of NeoPixels you have connected
pixel_num = 30
pixels = neopixel.NeoPixel(pixel_pin, pixel_num, brightness=0.5, auto_write=False)
comet = Comet(pixels, speed=0.02, color=JADE, tail_length=10, bounce=True)
while True:
comet.animate()
Note the line where you create the comet object. There are a number of items inside the parentheses. In this case, you're provided with a fully working example. But what if you want to change how the comet works? The code alone does not explain what the options mean.
So, in the API Reference documentation list, click the adafruit_led_animation.animation.comet link and scroll down a bit until you see the following.
Look familiar? It is! This is the documentation for setting up the comet object. It explains what each argument provided in the comet setup in the code meant, as well as the other available features. For example, the code includes speed=0.02. The documentation clarifies that this is the "Animation speed in seconds". The code doesn't include ring. The documentation indicates this is an available setting that enables "Ring mode".
This type of information is available for any function you would set up in your code. If you need clarification on something, wonder whether there's more options available, or are simply interested in the details involved in the code you're writing, check out the documentation for the CircuitPython libraries!
Other Links
This section is the same for every library. It includes a list of links to external sites, which you can visit for more information about the CircuitPython Project and Adafruit.
That covers the CircuitPython library documentation! When you are ready to go beyond the basic library features covered in a guide, or you're interested in understanding those features better, the library documentation on Read the Docs has you covered!
