Page 1 of 1

ESP32 documentation

Posted: Sat Dec 01, 2018 11:32 pm
by mattyt
Hi folks,

With some help (thanks Oliver and Sean!) we've cloned the ESP8266 documentation and renamed it to ESP32:

https://micropython-docs-esp32.readthedocs.io

My goal now is to update that documentation. If anyone would be prepared to help out please let me know - I'd be happy to accept pull requests!

https://github.com/mattytrentini/micropython

For the record, as well as more accurately describing the ESP32 port I'm seriously considering introducing an even simpler Quick Reference that applies to all ports (at least PyBoard/8266/32). This could live under General Documentation for MicroPython. Then the port-specific quick references should only describe differences or features unique to that port (and we should strive to minimise those differences!).

Anyway, any comments, feedback or assistance would be very welcome!

Re: ESP32 documentation

Posted: Sun Dec 02, 2018 12:12 am
by rpr
This is a great start. I'm happy to help. I will take a look to see what areas I can do so. Somewhat of a newbie still.

Re: ESP32 documentation

Posted: Sun Dec 02, 2018 4:26 am
by OutoftheBOTS_
I am very busy ATM but this is something that I might be able to contribute.

I suggest if someone say once a month posts a reminder on this thread will help remind people.

I assume for someone to help out on the doc they would just branch on github then write what they though on the docs the send a PR???

Re: ESP32 documentation

Posted: Sun Dec 02, 2018 4:27 am
by OutoftheBOTS_
For the record, as well as more accurately describing the ESP32 port I'm seriously considering introducing an even simpler Quick Reference that applies to all ports (at least PyBoard/8266/32). This could live under General Documentation for MicroPython. Then the port-specific quick references should only describe differences or features unique to that port (and we should strive to minimise those differences!).
This is what Lobo does, he only documents what's different for his port from mainstream.

Re: ESP32 documentation

Posted: Thu Dec 06, 2018 8:53 pm
by mattyt
OutoftheBOTS_ wrote:
Sun Dec 02, 2018 4:26 am
I assume for someone to help out on the doc they would just branch on github then write what they though on the docs the send a PR???
Yep!
Technically: Fork the repository [1], make changes then raise a PR [2].
OutoftheBOTS_ wrote:
Sun Dec 02, 2018 4:26 am
I suggest if someone say once a month posts a reminder on this thread will help remind people.
Can do. Will also post periodic updates. So far we've had a couple of PR's from RPRR (thanks!) who was kind enough to update the Technical Specifications and datasheets and how to write the flash.
I've added the Capacitive Touch interface. Next up I'm keen to update PWM to cover the different ranges (up to 40MHz but with a drop in duty resolution as the freq increases). That feature only appeared yesterday by the way; thanks Damien!

[1] ie make a clone of my micropython repository in your account
[2] on my repository to pick up your changes

Re: ESP32 documentation

Posted: Fri Dec 07, 2018 5:02 am
by hanson.alex
I'd like to help with a) esp32 docs and b) general micropython docs. For item b) I agree with @mattyt that micropython needs to have a better quick reference that is more general and describes some of the existing documentation limitations / gotchas.

It seems within the realm of possibilities to create a unified API for all micropython ports. This unified API could be generated automatically using a python script. It could use the code's doc string to check function signatures, flag any that can not be merged automatically, for functions that do not exist they for a given port they could return either NotImplementedError or PortCompatabilityError. Then the documentation generator could look for NotImplementedError and PortCompatabilityError to supplement. Thoughts?

Also, does anyone know if this form supports anytime of markup?

Thanks guys!

Re: ESP32 documentation

Posted: Sat Dec 08, 2018 11:04 pm
by mattyt
I'd like to help with a) esp32 docs and b) general micropython docs.
[/quote]
Great! Every little bit of help is very welcome. :)
hanson.alex wrote:
Fri Dec 07, 2018 5:02 am
It seems within the realm of possibilities to create a unified API for all micropython ports. This unified API could be generated automatically using a python script. It could use the code's doc string to check function signatures, flag any that can not be merged automatically, for functions that do not exist they for a given port they could return either NotImplementedError or PortCompatabilityError. Then the documentation generator could look for NotImplementedError and PortCompatabilityError to supplement. Thoughts?
Yes, I think this would be helpful! Any effort to keep the ports compatible would be useful. I suspect the problem you'll face is encouraging the use of the generator - it seems more typical to start a port by copy 'n' pasting from an existing one...

I've been considering tackling this issue from the other side. For a while I've wanted to create a MicroPython script to run on each port and check that the interfaces are correct. A naive implementation could be so simple as to just check for the presence of method names in each module. Something like:

Code: Select all

all(word in dir(machine.I2C) for word in ['readfrom', 'write'])
It could be built up to produce a diff as to how the api's differ from the canonical definition.

We could also put in some rules so even if we accept that CircuitPython has moved I2C we could check that the methods match.
hanson.alex wrote:
Fri Dec 07, 2018 5:02 am
Also, does anyone know if this form supports anytime of markup?
It does but it's quite an old style. You can discover how to mark up your text by clicking the formatting buttons above the text field when you edit - or refer to one of the guides on formatting with phpBB/BBCode.