3

How do I configure sphinx to document modules intended for a MicroPython interpreter?

The fundamental problem I'm facing is that sphinx gets the information it documents from the imported module. Therefore the python interpreter used to document a module must be importable into that interpreter.

First Problem

I'm using a pyboard, so naturally

import pyb

cannot find module pyb... So I added to conf.py

from unittest.mock import MagicMock
sys.modules['pyb'] = MagicMock()  # and many more

Second Problem

One of my MicroPython libraries is called cmd

Exception occurred:
  File "/usr/lib/python3.5/pdb.py", line 135, in <module>
    class Pdb(bdb.Bdb, cmd.Cmd):
AttributeError: module 'cmd' has no attribute 'Cmd'

So that makes sense... I changed the name of the module to ucmd, and that appears to be working... but it's suuuuuper dodgy.

Question

Is there a proper way to do this? To sphinx document a module not designed for the platform running the sphinx-build command?

Phrased more practically: if I wanted to document a MicroPython module called collections, subprocess, or io (all of which are used by the sphinx library), is it possible to use sphinx to do so?

Or would I simply have to be content with naming them ucollections, usubprocess, and uio respectively?

FraggaMuffin
  • 3,915
  • 3
  • 22
  • 26
  • apart from sphinx, would you be helped if you could 'just import' most (not all) of micropythons stdlib modules ? – Jos Verlinde Sep 16 '21 at 19:27
  • @JosVerlinde The issue was with the conflict of imports, using `cmd` as an example, I had the choice of either: 1) importing micropython's cmd module, and sphinx wouldn't load, or 2) documenting the system's `cmd` module, which wasn't the point. So 'just import'ing raised one of those two problems.... whereas an Abstract Syntax Tree (ast) approach to auto-documenting wouldn't have that problem, but I don't believe sphinx supports that. I've been working successfully on a system for over 2 years now, I should really reply here with my experiences & what I've found works best. – FraggaMuffin Sep 19 '21 at 12:28

1 Answers1

0

Below is not a sphinx solution, but does provide for a partial autocompletion in most modern editors.

to generate stubs for a (custom) MicroPython module you could use the MicroPython-Stubber

for configuration for a custom module see section 4.4

Alternatively in that same repro in various tests I import the MicroPython-CPython stubs ( sourced from micropython-lib and pycopy-lib) by inserting that that in CPython's sys.path. This works very well for my testing purposes, allowing me to run and debug (hardware agnostic) MicroPython code with no or little alteration on CPython. Perhaps it suits your documentation needs as well.

Jos Verlinde
  • 1,468
  • 12
  • 25