aseba
aseba copied to clipboard
Mobsya
Documentation migration
I'm in the process of moving some of the documentation from https://www.thymio.org/en:start to github and readthedocs. My initial goal was to use markdown but I'm reconsidering that choice and will use reStructuredText instead, which will work best for documenting APIs especially since there are some maths formulas. The process is unfortunately not automatic - at least not full and there is a lot of clean up to do, both because formatting issue and outdated content.
I suggest we keep the "outdated" information where they are and focus on what's relevant to 1.6+. We should spread the efforts over several weeks or months since it's quite tedious and there are more pressing matters. I think I will focus on the language/apis first since there are no questions regarding the content and move from there.
Added by @stephanemagnenat: As pointed out by @cor3ntin, we need to come with a structure for the documentation to be put on readthedocs. Here is what I propose:
Aseba
- [x] About: brief overview of Aseba's history and concepts, content of https://www.thymio.org/en:start and https://www.thymio.org/en:asebaconcepts, also an explanation that each target has a different programming interface (see section targets)
- [ ] Getting started: an updated version of https://www.thymio.org/en:gettingstarted, later challenge is to be incorporated into playground.
- [x] Studio, the text programming environment, content of https://www.thymio.org/en:asebastudio, https://www.thymio.org/en:asebastudioplot and https://www.thymio.org/en:thymioflash
- [x] Playground, the robot simulator, general introduction to playground, partial content of https://www.thymio.org/en:thymiosimulation and https://www.thymio.org/en:asebaplayground
- [ ] Switch, a combination of new information for the new switch, https://www.thymio.org/en:asebaswitchremap and https://www.thymio.org/en:asebamedulla
- [ ] Command line tools, a description of the existing command line tools
- [x] The language, content of http://aseba.readthedocs.io/en/latest/aseba-language.html
- [x] Native functions standard library, content of http://aseba.readthedocs.io/en/latest/aseba-std-natives.html
Targets
- [x] Thymio, documentation of the launcher, the firmware upgrader and network configurator tools, and content of http://aseba.readthedocs.io/en/latest/thymio-api.html ~ - [ ] E-puck, to be written ~ ~ - [ ] Elisa 3, to ask Gilles ~
Not all these need to be added at once, but we should agree on the structure as soon as possible.
I agree with using reStructurdedText, I reached the same conclusion.
Regarding content, indeed we need to do clean-up. This can be a team effort, and we can coordinate from this issue. However, it would be good not to delay this too long as the offline doc is currently out of date and this is getting worst with every release.
I agree about starting from the language/APIs.
First file uploaded https://github.com/cor3ntin/aseba/blob/clean_doc/doc/aseba-language.rst
First file uploaded https://github.com/cor3ntin/aseba/blob/clean_doc/doc/aseba-language.rst
The table Expressions and assignments has formatting errors.
The native functions are all done. Unfortunately, github does not support maths formula so you won't see the file properly, but it will works fine on readthedocs https://github.com/cor3ntin/aseba/blob/clean_doc/doc/aseba-std-natives.rst
There are a few questions regarding the docs that readthedocs does not solves
- We have source code documentation ( aka Doxygen ) that lives separately from the project documentation, should we try to merge the two ?
- We have api doc for the new http webbridge - we should definitively put that somewhere - should we merge that with the other docs ?
If so, is read the doc the right place ? Maybe we could have a git repo dedicated to generated / transformed docs served on github.io
These are good points! My feeling:
- The source code documentation is for developer and Doxygen is fine for that. Its coverage and quality should be improved over time, but there is no urgency there.
- While the API doc for the HTTP module of new Switch has been created by a third-party tool, the final aim is for it to be automatically generated by the HTTP module, as such it is a dynamic content. We could move the original documentation or the regenerated one into a page at readthedocs, but maybe it is overkill, rather we should put a documentation page about the new switch and mention how to query the HTTP API documentation dynamically.
I was not suggesting that doxygen be replaced; It's more about
- Not having generated docs in the main repo
- Not having the documentation spread accross multiple domain names so people now where to look for it.
Being curious, I looked up what existed and Doxygen is probably still our best bet. There is this project https://github.com/sourcey/moxygen that transforms Doxygen output to markdown I we want.
The question of where to put the generated doxygen documentation is indeed always annoying. We could actually put them within each release, along with the binaries, what do you think?
I tend to look for documentation online, so I would expect to find it on readthedocs ( or equivalent ) in html form- but that may well be a very personal preference.
I see your point, it would be nice to have it on readthedocs, but we really do not want to commit it in the repository. I did it for Dashel and I feel it is a bad idea.
I added the proposed structure at the top of this issue.
@cor3ntin could you please briefly document the migration process, so that third parties could help?