Document esp module for ESP8266 #1289
Conversation
|
Thanks @deshipu! Well, these things need to be documented if we want people to be able to actually use this port, and this seems like the right place to put them. @danicampora Are you going to document the cc3200's specific modules in a similar way? |
|
Yes, in fact I am working in the cc3200 docs as we speak ;-). But my current plan is to put everything inside |
But will they be in Sphinx format? If so, why not make them part of the full docs in docs/? |
Yes exactly in the same format as the current docs.
Because with the CC3200 may things are slitgly different to stmahl (I already made those differences minimal, but still they exist) and many things there apply only to stmhal or a "full" port of uPy. A quick example, the Pin constructor is different for stmhal, cc3200 and ESP8266. How do you see those 3 ports sharing the same |
Yes, we'll need a separate section for the different boards.
It should be the same :) ESP is a subset of stmhal, so we can use the same documentation for both with a note for extensions provided by stmhal. Similar situation for cc3200, no? |
That's the point, it's not "exactly" the same. I think docs are going to be very confusing once we start having more variants which only support a certain subset of the features. In my opinion there should be a separate Well, let's see what the others think... |
|
Yes, I know this implies having "duplication" in the docs and hence more work for us, but it will also mean having very accurate and easy to read documentation, which I believe is the goal here. |
|
How about merging this now, and restructuring the documentation when we know how we want it to look, moving it in the rigth place then? |
Sure, that's fine by me. |
This idea, but the reality about which @danicampora writes is what hold me from better documenting unix port. For example, unix port has termios (or utermios) module. But the main "product" of MicroPython is PyBoard, how useful and non-confusing for PyBoard users would be to read about termios module, even if somewhere there's a fine-print that it's available only in unix port? And that's the simple case, what if methods present/absent, parameters present/absent, behavior is different? Now that there're 2 "products", I'll let you guys figure out how to deal with that ;-). We need something like #ifdef for Sphinx... |
|
I actually don't think we want #ifdef for Sphinx. I think we want to document all of the versions. If people are actually using the unix port, then its definitely useful to document what's actually available and implemented. |
|
I actually don't think we want #ifdef for Sphinx. I think we want to document all of the ports. If people are actually using a given port, then its definitely useful to document what's actually available and implemented. |
|
Soo, maybe we could have the available classes/modules documented in individual files (as right now), with notes about differences in how they work, and then have pages for each of the ports, with different TOCs including only the available modules in that port? This way we don't have much duplication, and there is an incentive to make all ports behave the same if possible. |
Like, for dozen of ports have dozen of doc trees, 90% the same? Or split those 90% out, and have "diff" per-port? Like, 2 method of a module are described in "generic" doc, and 3 in port-specific doc, and let people figure out what's where? |
Yeah, both options suck, I agree. |
|
I think that you use whatever is appropriate. For example, if the Pin module for PORT-X is virtual identical to stmhal, then it makes sense to say that and list the differences. If the module doesn't exist anywhere else, then it makes sense to document it in that port. But not having documentation for the 10% that's different makes it extremely frustrating for users trying to use micropython. |
|
Another approach is to be able to annotate options to say that a particular option is or isn't implemented on a particular port. (maybe PULL_DOWN gets a little ESP with an X through it or something). Just tossing out ideas. |
Imagine you were not a developer but an user, you just unpacked your uPy powered board and you go to the docs to learn how to use it, and the docs are layout in the way you describe it. How would you feel? Probably a bit frustrated because there's a lot of info that doesn't apply to your board and to find out what it does apply you need to search in many different places. We are (at least I am ;-)) claiming that Micro Python makes embedding developing easy and fun, and the documents are crucial in making this true. Maybe the #ifdefs approach is something we need in order to avoid duplication as much as possible, but also a new folder structure.
This is good and we should aim for that, but it's not always possible. I am changing the CC3200 port a lot to make it's API as similar as possible to stmhal. In many places the case is that I wrote the API to resemble the underlying hardware implementation, which is not always a good choice, then I check stmhal and I see that @dpgeorge approach seems more generic and applicable to other platforms, so I adapt to it. In other places this is just not as easy without scarifying functionality or adding code bloat. I just feel that if we use 1 doc tree for all ports full of notes about the differences, we are going to have a lot of frustrated users. |
|
If we can manage to have a "single" doc source tree that can be used to generate separate htmls for each port (#ifdef like approach), then that's what I think we should do. |
|
I have never written and deployed a web page for public consumption, so any suggestions I make should be considered with that in mind - but I'm thinking that for sections of the documentation where there is substantial but incomplete overlap between ports we could display all of the text for all of the ports, with a menu to select the port you are interested in, and gray-out the parts that aren't relevant to your port. That way you can see the complete documentation on one page, with the differences clearly displayed in a way that the user can see which parts are relevant to each port. |
|
I am looking at the sphinx documentation and I don't see anything that we could use out-of-the-box. I saw the python makedocs.py --board=wipyThis hypothetical |
|
If we go down the route of multiple generated versions of the docs then we probably can't use readthedocs server. That's not a problem (we can use the micropython.org server) but it requires time and effort to set up. |
I have never seen a user who would build and read the docs in the tree that he checked out, instead of simply reading it online, when that is available. The only time where we build it is either when we are not online, or when we want to check the changes we just made... So I think we would need to have all those versions online. There is no So I think it would make sense to have several starting documents for different boards, with corresponding Sphinx configuration files, and then, on Readthedocs, have several projects, each using the same repository but different configuration file (they allow to change that). Where the starting documents and config files for each of the boards should be located within the filesystem, I'm not sure -- either in the port's |
That's exactly what I meant. It also has the important trait @deshipu mentions - "there is an incentive to make all ports behave the same if possible.", while of course being realistic and allow differences in manageable way. |
You miss the point raised above - that same module for different ports may have different contents, different descriptions of each item, etc. |
Any text file (well, almost any), having passed thru C preprocessor, magically acquires that ability. |
That's not a problem, just describe the modules that differ in their own files, and include them only in the TOC of the port to which they belong. |
That's what we want to avoid because many modules share a lot in common with differences here and there, so we want to reuse the documentation of that module as much as possible, only having to write the difss, and then the generated |
|
OK, I was wrong, there actually is |
Cool! that seems to be what we need :-) |
Furthermore, a benefit of having selectively compiled documentation is that it's very easy for developers to see exactly what the differences are between ports. At the moment you'd have to view the code from each port to see how they work, but if they are all documented in the same file then it's much easier. |
|
I am going to give it a try using the |
I'd say you don't need to add any directories: everything can go in the top-level docs/library directory. There won't be any name clashes because if 2 ports define the same module then they should both be documented together in the same file (using ..only:: for differences). Any port-specific modules like |
|
@deshipu : So, I guess you also may want to play with ::only in "docs/library/index.rst" patch. |
|
OK, I made the esp8266 part optional, we will probably want to restructure that when splitting the docs anyways. |
I document as much as I could guess from experiments and reading the code for the ``esp`` module for the ESP8266 port of Micropython. For now the tag has to be set manually with -t option when building, when we have properly split documentation, there will be a separate config file for esp8266 with that tag set.
|
@pfalcon Squashed. |
|
@pfalcon Yes, it works as expected. I tested it by temporarily adding |
Yes, but no-one will see the new docs because esp8266 is never defined! |
|
Merged in 78ccb44. I renamed the variable to "port_esp8266" since we might also want a unix and windows configuration and the variables "unix" and "windows" could very easily clash with other internal Sphinx variables (so they would now be "port_unix" and "port_windows"). To build with a specific config option turned on use: |
Someone who cares should set up a new readthedocs project which will build the docs with that tag defined. Ideally, that should be project maintainers, to keep stuff organized, but I guess they don't have time (and if they have, working on e.g. #1295 is more important (at least because it covers something which was in work for 1+ years)). |
I think having a separate rtd project per port is bloat/overkill/difficult to maintain. Eg you'll need to log into each one to build them when a new release comes out. We need to at least solve this problem for the case of unix, pyboard and wipy docs, and if the solution is scalable then it's easy to add esp8266, teensy, etc. |
|
I think that's actually the sanest way to proceed. You don't need separate logins to manage the projects -- they have a working user/ownership system. You don't even need to log in to trigger a build, it's just a POST to a public address. You can even set up github to trigger builds automatically on new commits. Of course, the "official" docs should probably default to a stable branch -- but that's also easy to setup. |
|
We can actually have them as subprojects of the mircopython project, then they will live under the same URL. |
You do need to log in if there is a new release/tag, and then select the new tag in the versions list. |
|
@dpgeorge what other options do we have? Do you have an alternate suggestion? |
There is always the "do it yourself" option, which I definitely prefer :) Ie host the docs at docs.micropython.org/"port name". |
|
Proof of concept: pyboard docs: http://micropython.org/resources/docs/pyboard/ This is rather easy to automate. Just need to work out how to get the version numbers (and languages) working. |
|
That's "do it myself" option ;-). If you can do that, very nice, and looks good! |
|
Looks great! |
…eio_pr_1289 Resubmit PR micropython#1289, "WIP: bleio rewrite" by @arturo182
I document as much as I could guess from experiments and reading the
code for the
espmodule for the ESP8266 port of Micropython.