Documentation migration

MobsyaBot commented 6 years ago

Issue by cor3ntin Monday Jan 15, 2018 at 17:46 GMT Originally opened as https://github.com/aseba-community/aseba/issues/780

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.

MobsyaBot commented 6 years ago

Comment by stephanemagnenat Monday Jan 15, 2018 at 19:41 GMT

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.

MobsyaBot commented 6 years ago

Comment by cor3ntin Tuesday Jan 16, 2018 at 10:25 GMT

First file uploaded https://github.com/cor3ntin/aseba/blob/clean_doc/doc/aseba-language.rst

MobsyaBot commented 6 years ago

Comment by stephanemagnenat Tuesday Jan 16, 2018 at 10:58 GMT

First file uploaded https://github.com/cor3ntin/aseba/blob/clean_doc/doc/aseba-language.rst

The table Expressions and assignments has formatting errors.

MobsyaBot commented 6 years ago

Comment by cor3ntin Wednesday Jan 17, 2018 at 09:43 GMT

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

MobsyaBot commented 6 years ago

Comment by cor3ntin Thursday Jan 18, 2018 at 08:40 GMT

The work is being down here #792

MobsyaBot commented 6 years ago

Comment by cor3ntin Wednesday Jan 31, 2018 at 08:44 GMT

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

MobsyaBot commented 6 years ago

Comment by stephanemagnenat Wednesday Jan 31, 2018 at 08:54 GMT

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.

MobsyaBot commented 6 years ago

Comment by cor3ntin Wednesday Jan 31, 2018 at 09:03 GMT

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.

MobsyaBot commented 6 years ago

Comment by stephanemagnenat Wednesday Jan 31, 2018 at 09:17 GMT

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?

MobsyaBot commented 6 years ago

Comment by cor3ntin Wednesday Jan 31, 2018 at 09:21 GMT

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.

MobsyaBot commented 6 years ago

Comment by stephanemagnenat Wednesday Jan 31, 2018 at 09:23 GMT

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.

MobsyaBot commented 6 years ago

Comment by stephanemagnenat Wednesday Jan 31, 2018 at 09:25 GMT

I added the proposed structure at the top of this issue.

MobsyaBot commented 6 years ago

Comment by stephanemagnenat Tuesday Feb 06, 2018 at 09:58 GMT

@cor3ntin could you please briefly document the migration process, so that third parties could help?

MobsyaBot commented 6 years ago

Comment by cor3ntin Tuesday Feb 06, 2018 at 10:12 GMT

@stephanemagnenat I wished there was one... but the scripts are failing me. at this point it's basically pick a source from the wiki and manually change all the markups until it's a valid reStructuredText document

Mobsya / aseba

Documentation migration #61

Aseba

Targets