Season of Docs : MicroPython

[MisterAwesome23]

Hello guys, my name is Manthan Admane and I am a Computer Engineering student.
I would love to a part of the community and contribute

I want to work on Extend coverage of existing ports- choosing ESP32 primarily. Any tracks on getting started, any help, suggestion or feedback would be appreciated.

Thank you.

[Yomdroid]

Hello,
Regarding my interest in the GSoD Idea Create a Getting Started Guide, here’s a brief outline of what I intend for it to cover based on the idea description:

Introduction
A brief on what to expect from the guide and prerequisites.

An Overview of MicroPython

• What is MicroPython?

• What is a Microcontroller

• It’s application and importance

• Features and limitations

• MicroPython vs Python

• Boards that support MicroPython

How the REPL works

• What is a REPL?

• Serial terminal connection

• WebREPL

How to install MicroPython on your board

• Installing uPyCraft for Windows, Linux or Mac OS.

• Updating firmware if the board comes with MicroPython installed, on Linux, Windows or Mac OS.

• Step by step process supported with either a video or an illustration, and or pictures. On Linux, Windows or Mac OS.

How to create an application
This will cover creating and deploying code using uPyCraft and REPL.

Simple tutorial(s)

• Connect to a board and toggle a GPIO

• A blinking LED

FAQs
To cover common problems and possible solutions or misconceptions.

I’d appreciate any feedback or suggestions.

[hlovatt]

A suggestion re. improving the docs.

I'm currently writing a typeshed for the PyBoard, if a typeshed were written for all the libraries and then the documentation was generated from the typeshed this would have advantages:

1. The documentation would be better structured, i.e. everything would be in its correct place. So for examples constants would not be listed at the end, but before methods (as they are in python code). There wouldn't be notes at the end, like "Hardware Note" in `pyb.Accel`, they would be included in the class doc string instead.
2. The documentation would be consistent with the typeshed as used by IDEs like PyCharm and VS Code and by MyPy.
3. IDEs and MyPy can catch errors before code is run, with the errors matching the documentation.
4. IDEs can provide documentation pop ups, that is the same as the documentation.
5. IDEs can provide code completion, that matches the documentation.
6. The documentation would include the type information. Which can be really helpful; e.g. when the documentation says "array", does it mean `uarray.array`, `bytes`, `bytearray`, list, any of these?
7. Whould specify which function arguments were positional only, which are positional or keyword, which are keyword only?

The typeshed -> document conversion could be something along this line.

As a side note, having a typeshed as the 'source-of-truth' will be helpful as MicroPython moves to support latter versions of Python which are increasingly using type hints and will be valuable for viper.

[mattyt]

Take a look at micropython-stubber and micropy-cli. Should do what you're after?

[hlovatt]

Take a look at micropython-stubber and micropy-cli. Should do what you're after?

I'm aware of these projects. The problem with them is that they are generated on the PyBoard (or whichever board) and therefore do not contain docs, arguments, nor types.

Taking a simple example; the `exp()` function, their stubs contain:

Code: Select all

def exp():
    pass

I would like something like:

Code: Select all

def exp(x: float) -> float:
    """
    Return e**x.
    """

IE the argument names, the argument types, the return type, and a doc comment.

The approach I'm taking in generating my stubs is to scrape the MicroPython documentation rst files and generate the stubs (typeshed) from these.

[JoeCharlieH]

IE the argument names, the argument types, the return type, and a doc comment.

The approach I'm taking in generating my stubs is to scrape the MicroPython documentation rst files and generate the stubs (typeshed) from these.

It's an excellent idea creating stubs from the documentation instead of the compiled binary inside the boards. This will be great after all the documentation is finished and with an ordered structure.

My main question is, is it possible to create the stubs from source? IE. the C module espneopixel.c

Also, is all the documentation made by "hand"?

[hlovatt]

My main question is, is it possible to create the stubs from source? IE. the C module espneopixel.c

That's an interesting idea; but sorry don't know if its practical, I've only glanced at the source code. You would still need to parse the document rst files to get the doc comments.

Also, is all the documentation made by "hand"?

I don't know how the documentation is made, looking at its free form style I would definitely guess that it is totally hand written. One of the advantages of generating a typeshed is that it adds a structure to the documentation.

However I'm adding to the 'hand-written' nature because I'm hand writing the types, some of which are very complicated!

[jnanjeky]

Thanks all for your feedback.

i submitted my proposal for the project on documenting internals.

Best,
Joannah

[Zenix27]

Thanks Jim and Matt for the feedback and information in the above posts

I have also applied for Season of Docs Project titled "Fabricating Getting Started and Revamping the Downloads Page"
and also contributed to MicroPython Docs, here is a PR https://github.com/micropython/micropython/pull/6239

[aivarannamaa]

I'm developing Thonny IDE and I'm glad you are thinking about how an IDE can use the documentation.

One tricky issue is that different ports of MicroPython come with different set of modules which may include different functions. It would be great if the documentation work done on one port could be reused and tweaked for other ports.

Would it work if the typeshed contained "master" pseudo-modules from where specific ports would import selected definitions into their typeshed modules? The master modules could be maintained by MicroPython team, one branch per MP release. Each port could fork the repo and add their derived final modules with easy path to synchronize the master modules from the upstream. Just an idea

About generating documentation from the C code -- it looks like CircuitPython people have considered it: https://github.com/adafruit/circuitpyth ... 3107/files