Current documentation v. github repository

All ESP8266 boards running MicroPython.
Official boards are the Adafruit Huzzah and Feather boards.
Target audience: MicroPython users with an ESP8266 board.
slzatz
Posts: 92
Joined: Mon Feb 09, 2015 1:09 am

Current documentation v. github repository

Post by slzatz » Sat Mar 19, 2016 4:32 pm

The current Quick Reference for the esp8266 includes capabilities like SPI, I2C that do not appear to be implemented in the github repository (unless they have moved from the machine module). Would it make sense to put one sentence at the beginning of the quick guide that the text may not match the actual available functionality at this stage of development?

User avatar
thoralt
Posts: 8
Joined: Wed Jul 02, 2014 11:22 am
Location: Germany

Re: Current documentation v. github repository

Post by thoralt » Sat Mar 19, 2016 5:36 pm

slzatz wrote: [...] may not match the actual available functionality at this stage of development?
The functionality _is_ available in the alpha versions of the firmware which were shipped to certain Kickstarter backers (depending on how much you donated). It is not yet available in Github, but the Micropython folks are very busy cleaning up code and implementing new features and will upload the modules on Github when they are ready.

User avatar
deshipu
Posts: 1346
Joined: Thu May 28, 2015 5:54 pm

Re: Current documentation v. github repository

Post by deshipu » Sat Mar 19, 2016 6:55 pm

But it kind of makes sense to keep the documentation in sync with the code in the repository. It's a kind of tradition (or at least basic assumption) in the open source (and not only) world, that the documentation you get with the code applies to that code, not something completely different that you don't even have access to.

Perhaps it would make sense to put the quickstart guide for the alpha binaries somewhere else (a branch of that repository, maybe), so that there is no confusion?

pfalcon
Posts: 1153
Joined: Fri Feb 28, 2014 2:05 pm

Re: Current documentation v. github repository

Post by pfalcon » Wed Mar 23, 2016 12:03 pm

No, documentation matches code only at the release points. And there was no release for MicroPython ESP8266 port yet. If you find that confusing, please kindly wait for the release.
Awesome MicroPython list
Pycopy - A better MicroPython https://github.com/pfalcon/micropython
MicroPython standard library for all ports and forks - https://github.com/pfalcon/micropython-lib
More up to date docs - http://pycopy.readthedocs.io/

User avatar
deshipu
Posts: 1346
Joined: Thu May 28, 2015 5:54 pm

Re: Current documentation v. github repository

Post by deshipu » Wed Mar 23, 2016 11:46 pm

Fair enough.

MaartenB
Posts: 4
Joined: Thu Mar 24, 2016 8:42 pm

Re: Current documentation v. github repository

Post by MaartenB » Thu Mar 24, 2016 8:55 pm

I'd like to add that currently it is very confusing what the status is of the esp8266 port. I landed on the github page, managed to compile it. After reading this forum and some documentation I thought there was something like a filesystem, and spi etc, but that didn't work. Only digging through this forum and the kickstarter page I found out what the situation is (people getting early access to firmwares). Maybe it is useful to put this in the README.md to not waste people's time. Really looking forward to see version 1.0! :)

pfalcon
Posts: 1153
Joined: Fri Feb 28, 2014 2:05 pm

Re: Current documentation v. github repository

Post by pfalcon » Thu Mar 24, 2016 11:14 pm

There's a README, and it would be among the first things you browse after landing on github, and it gives the actual state of the port (well, more actual than anything else you can find, the only more actual thing is a git commit log):
https://github.com/micropython/micropyt ... er/esp8266 .
Awesome MicroPython list
Pycopy - A better MicroPython https://github.com/pfalcon/micropython
MicroPython standard library for all ports and forks - https://github.com/pfalcon/micropython-lib
More up to date docs - http://pycopy.readthedocs.io/

MaartenB
Posts: 4
Joined: Thu Mar 24, 2016 8:42 pm

Re: Current documentation v. github repository

Post by MaartenB » Fri Mar 25, 2016 8:25 am

True, but this forum and the documentation led me to believe that README was out of date, I didn't know the thread 'New mp-esp8266-firmware-vXY.bin on ESP8266' was about a firmware that was released for backers only. May be useful to mention the kickstarter and this forum on the README.

slzatz
Posts: 92
Joined: Mon Feb 09, 2015 1:09 am

Re: Current documentation v. github repository

Post by slzatz » Fri Mar 25, 2016 11:53 am

I hate to be a pain here and I think the whole micropython project in general and the port to the esp8266 are brilliant (and I've been a backer of every micropython-related kickstarter project) but when you go to the first page of the documention and it says:
MicroPython documentation

Welcome! This is the documentation for MicroPython v1.6, last updated 25 Mar 2016.

MicroPython runs on a variety of systems and each has their own specific documentation. You are currently viewing the documentation for the ESP8266.
How could anyone possibly know that the esp8266 port isn't released yet and that the documentation doesn't match the current reality of the git repository? It seems fairly obvious that this is a problem that could be substantially mitigated with one sentence that said that the documentation is not consistent with the repository.

User avatar
platforma
Posts: 258
Joined: Thu May 28, 2015 5:08 pm
Location: Japan

Re: Current documentation v. github repository

Post by platforma » Wed Mar 30, 2016 12:44 pm

MaartenB wrote:I didn't know the thread 'New mp-esp8266-firmware-vXY.bin on ESP8266' was about a firmware that was released for backers only.
I do agree with you and the title of that thread is not particularly descriptive. The kickstarter page did go on about explaining the alpha versions of firmware distributed to a number of backers with different pledges. And it was also mentioned in the last update.
Creator Damien George on March 16 wrote: An alpha release of the code has been emailed to supporters at the GBP35 and higher levels.
You can refer to the unofficial guide, in which I describe the alpha phase of the port. Please do bear in mind that work is being done constantly to bring out the "alpha" release with as little issues as possible to all the backers, and Damien and Paul are doing their best.

Post Reply