Current documentation v. github repository
Current documentation v. github repository
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?
Re: Current documentation v. github repository
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.slzatz wrote: [...] may not match the actual available functionality at this stage of development?
Re: Current documentation v. github repository
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?
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?
Re: Current documentation v. github repository
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/
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/
Re: Current documentation v. github repository
Fair enough.
Re: Current documentation v. github repository
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! 
Re: Current documentation v. github repository
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 .
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/
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/
Re: Current documentation v. github repository
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.
Re: Current documentation v. github repository
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:
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.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.
Re: Current documentation v. github repository
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.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.
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.Creator Damien George on March 16 wrote: An alpha release of the code has been emailed to supporters at the GBP35 and higher levels.