Season of Docs : MicroPython

General discussions and questions abound development of code with MicroPython that is not hardware specific.
Target audience: MicroPython Users.
MisterAwesome23
Posts: 1
Joined: Thu Jun 04, 2020 8:02 pm

Re: Season of Docs : MicroPython

Post by MisterAwesome23 » Thu Jun 04, 2020 8:05 pm

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
Posts: 2
Joined: Sun May 24, 2020 1:38 pm
Contact:

Re: Season of Docs : MicroPython

Post by Yomdroid » Fri Jun 05, 2020 5:46 pm

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
Posts: 40
Joined: Thu Aug 15, 2019 3:52 am
Location: Sydney

Re: Season of Docs : MicroPython

Post by hlovatt » Wed Jul 01, 2020 12:31 am

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.

User avatar
mattyt
Posts: 291
Joined: Mon Jan 23, 2017 6:39 am

Re: Season of Docs : MicroPython

Post by mattyt » Wed Jul 01, 2020 1:13 am

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

hlovatt
Posts: 40
Joined: Thu Aug 15, 2019 3:52 am
Location: Sydney

Re: Season of Docs : MicroPython

Post by hlovatt » Wed Jul 01, 2020 5:44 am

mattyt wrote:
Wed Jul 01, 2020 1:13 am
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
Posts: 8
Joined: Thu Dec 27, 2018 10:59 pm

Re: Season of Docs : MicroPython

Post by JoeCharlieH » Thu Jul 02, 2020 5:04 pm

hlovatt wrote:
Wed Jul 01, 2020 5:44 am

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
Posts: 40
Joined: Thu Aug 15, 2019 3:52 am
Location: Sydney

Re: Season of Docs : MicroPython

Post by hlovatt » Thu Jul 02, 2020 11:19 pm

JoeCharlieH wrote:
Thu Jul 02, 2020 5:04 pm
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.
JoeCharlieH wrote:
Thu Jul 02, 2020 5:04 pm
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
Posts: 6
Joined: Mon May 11, 2020 6:26 pm

Re: Season of Docs : MicroPython

Post by jnanjeky » Thu Jul 09, 2020 2:09 am

Thanks all for your feedback.

i submitted my proposal for the project on documenting internals.

Best,
Joannah

Zenix27
Posts: 1
Joined: Tue Jul 14, 2020 4:18 pm

Re: Season of Docs : MicroPython

Post by Zenix27 » Tue Jul 14, 2020 4:30 pm

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

User avatar
aivarannamaa
Posts: 40
Joined: Fri Sep 22, 2017 3:19 pm
Location: Estonia
Contact:

Re: Season of Docs : MicroPython

Post by aivarannamaa » Tue Jul 14, 2020 9:16 pm

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

Post Reply