Skill Level: Intermediate
I wrote the Documenting Python Programs With Sphinx tutorial a while back, but strangely enough, I have not been able to figure out how to generate documentation for CircuitPython programs on my primary computer, a Mac, until now.
The Problem
I write many CircuitPython programs for my tutorials. Although I provide little to no comments in the code shown in my tutorials (for readability), the code I place on GitHub accompanying those tutorials is fully commented to include additional information, such as the program’s description, circuit connections, library references, function parameters, code clarifications, and other details. Code comments are written using Python docstrings and extracted via the Sphinx Python Documentation Generator utility.
Up until now, I have been generating all of the documentation for those CircuitPython programs on my Raspberry Pi because the Sphinx program halts the generation process unless all library modules used by the program can be imported successfully. Even with the Blinka library installed on my Mac, the Sphinx program reports warnings like the following and will not generate the documentation.
WARNING: autodoc: failed to import module 'fireflies'; the following exception was raised: No module named 'board'
I have been trying all sorts of tricks and hacks in order to give myself the ability to generate the documentation on my Mac to no avail. Recently, I even tried using the u2if USB bridge firmware that allows you to run CircuitPython programs on your computer while still controlling the hardware of a connected board. Sounded promising, but alas, no such luck.
The Solution
Well, I finally discovered how to generate Sphinx based documentation for CircuitPython programs on my main computer. And fortunately, the solution is very simple. It involves adding the Sphinx autodoc extension’s autodoc_mock_imports option to the Sphinx conf.py configuration file. I added the following line to the General configuration section of the conf.py file for the fireflies.py CircuitPython program
autodoc_mock_imports = ["board", "digitalio"]
and it all worked beautifully! The option specifies a list of modules that will be mocked during generation making Sphinx no longer halt progress if they can not be imported. Add to the list any additional CircuitPython Core Modules, and other modules that could not be imported, that you are using in your program. For instance, the following was necessary for my motors.py program.
autodoc_mock_imports = ["board", "analogio", "countio", "digitalio", "pwmio", "adafruit_motor"]
Many people probably already knew this, but it is new to me. It is such a useful feature that I wanted to share it with you in case you did not know as well.
This quick tip is provided as a free service to our valued readers. Please help us continue this endeavor by considering a GitHub sponsorship or a PayPal donation. Thank you for joining me on this journey and I hope you enjoyed the experience. Please feel free to share your thoughts or questions in the comments section below.
Leave a Comment