Season of Docs : MicroPython
-
- Posts: 1
- Joined: Thu Jun 04, 2020 8:02 pm
Re: Season of Docs : MicroPython
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.
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.
Re: Season of Docs : MicroPython
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
This will cover creating and deploying code using uPyCraft and REPL.
Simple tutorial(s)
To cover common problems and possible solutions or misconceptions.
I’d appreciate any feedback or suggestions.
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
- What is a REPL?
- Serial terminal connection
- WebREPL
- 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.
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
To cover common problems and possible solutions or misconceptions.
I’d appreciate any feedback or suggestions.
Re: Season of Docs : MicroPython
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:
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.
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:
- 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.
- The documentation would be consistent with the typeshed as used by IDEs like PyCharm and VS Code and by MyPy.
- IDEs and MyPy can catch errors before code is run, with the errors matching the documentation.
- IDEs can provide documentation pop ups, that is the same as the documentation.
- IDEs can provide code completion, that matches the documentation.
- 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?
- Whould specify which function arguments were positional only, which are positional or keyword, which are keyword only?
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.
Re: Season of Docs : MicroPython
Take a look at micropython-stubber and micropy-cli. Should do what you're after?
Re: Season of Docs : MicroPython
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.mattyt wrote: ↑Wed Jul 01, 2020 1:13 amTake a look at micropython-stubber and micropy-cli. Should do what you're after?
Taking a simple example; the `exp()` function, their stubs contain:
Code: Select all
def exp():
pass
Code: Select all
def exp(x: float) -> float:
"""
Return e**x.
"""
The approach I'm taking in generating my stubs is to scrape the MicroPython documentation rst files and generate the stubs (typeshed) from these.
-
- Posts: 8
- Joined: Thu Dec 27, 2018 10:59 pm
Re: Season of Docs : MicroPython
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"?
Re: Season of Docs : MicroPython
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 pmMy main question is, is it possible to create the stubs from source? IE. the C module espneopixel.c
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!
Re: Season of Docs : MicroPython
Thanks all for your feedback.
i submitted my proposal for the project on documenting internals.
Best,
Joannah
i submitted my proposal for the project on documenting internals.
Best,
Joannah
Re: Season of Docs : MicroPython
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
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
- Posts: 171
- Joined: Fri Sep 22, 2017 3:19 pm
- Location: Estonia
- Contact:
Re: Season of Docs : MicroPython
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
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
Aivar Annamaa
https://thonny.org
https://thonny.org