Electronics Software Development

Quick Tip: Documenting CircuitPython Programs On Your Computer

Quick Tip Graphic
Written by John Woolsey

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.

About the author

John Woolsey

John is an electrical engineer who loves science, math, and technology and teaching it to others even more.
 
He knew he wanted to work with electronics from an early age, building his first robot when he was in 8th grade. His first computer was a Timex/Sinclair 2068 followed by the Tandy 1000 TL (aka really old stuff).
 
He put himself through college (The University of Texas at Austin) by working at Motorola where he worked for many years afterward in the Semiconductor Products Sector in Research and Development.
 
John started developing mobile app software in 2010 for himself and for other companies. He has also taught programming to kids for summer school and enjoyed years of judging kids science projects at the Austin Energy Regional Science Festival.
 
Electronics, software, and teaching all culminate in his new venture to learn, make, and teach others via the Woolsey Workshop website.

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.