Updating human-readable spec

[WasabiFan]

Now that our API surface for core functionality has been implemented, I've been trying to get the human-readable spec updated. I think this is still useful now that autogen works and is in use in multiple languages, but I'd like to hear others' thoughts on exactly what it should contain. In a separate branch, I have stripped out most of the content and replaced it with autogen logic to document the properties that we have in our spec. You can see the current version here.

It does not yet have any of the information that isn't in the JSON spec, and it also lacks a few other components that I just didn't get around to adding. The items that I can think of that it's missing are:

• Constructors
• Special properties
• Methods
• Special sensor classes

How do we want to add this content? We could add it to spec.json as real data, or we could manually write/copy the markdown and insert it dynamically (modify the autogen script to augment standard data). Thoughts @ddemidov?

[ddemidov]

I agree a human-readable version of the spec is useful, I am just not sure about the form. This could be just me, but I prefer using http://python-ev3dev.rtfd.org for reference (not only for python). I guess the ability to link to individual attributes and a TOC/index is what I like the most.

May be could replace the current markdown document with a sphinx generated site like that? That way we could just maintain spec.json and a couple of rst files with free-form content here, and the majority of the site could be autogenerated by readthedocs.org after each commit.

There is a bootstrap template available for sphinx wich supports bootswatch themes (I've been playing around with it recently: http://amgcl.rtfd.org), so we could even more or less match the interface to the primary ev3dev.org site. (wild idea: or merge the sites altogether?).

One problem with this I see right away is that it would probably be hard to use the autogen scripts on readthedocs.org, but I guess it would be easy to replace those with python just for this purpose.

What do you think?

[ddemidov]

Special sensor classes

I think we should just generate the list of those (together with their methods) from spec.json.

[WasabiFan]

This could be just me, but I prefer using http://python-ev3dev.rtfd.org for reference (not only for python). I guess the ability to link to individual attributes and a TOC/index is what I like the most.

My hope with the human-readable version is to have a good place that people can go if they want to create a new ev3dev-based library, so I'd want to make sure that it is as language-agnostic as possible. I view the spec as a "minimum bar" that any feature-complete ev3dev library will likely implement (ours or not), so I wouldn't want to base the generic docs on one implementation. But I'm not attached to any final form factor, so if we want to use a different service to do that I don't have an issue with it.

May be could replace the current markdown document with a sphinx generated site like that? That way we could just maintain spec.json and a couple of rst files with free-form content here, and the majority of the site could be autogenerated by readthedocs.org after each commit.

That sounds like a good end-goal, so I'm happy to work towards that.

There is a bootstrap template available for sphinx wich supports bootswatch themes (I've been playing around with it recently: http://amgcl.rtfd.org), so we could even more or less match the interface to the primary ev3dev.org site. (wild idea: or merge the sites altogether?).

Although we host the ev3dev-lang repo within the ev3dev organization, it's a separate project at the moment (and probably always will be). Simply put, the ev3dev name is just the core OS and drivers -- everything else is built upon that common base. To that end, it seems like we should keep any online documentation separated, at least for the ev3dev-lang project as a whole.

One problem with this I see right away is that it would probably be hard to use the autogen scripts on readthedocs.org, but I guess it would be easy to replace those with python just for this purpose.

I don't have an issue with this inherently, but I think you're underestimating the amount of work that would be needed to get our infrastructure re-written in Python. We'd need to re-write the core logic, file discovery, template parsing, content replacement, and filter extensions. And, we would need to re-make the templates themselves -- there are a lot of them. If we have a plan for the benefits that we would get out of this and they are significant enough to justify both the effort for us to update the templates as well as the scripts themselves, we can investigate further; but I think we'd need a pretty good reason to justify that investment. Otherwise, we can pick a system that works with what we have -- if that isn't a markdown document, maybe it's a Jekyll site on GH Pages or a documentation-focused service that allows you to upload custom data. I'm open to ideas.

I think we should just generate the list of those (together with their methods) from spec.json .

That's just something that I hadn't gotten around to when I made the original spec changes -- I do still plan to generate the sensor classes from the spec, regardless of the final destination.

[ddemidov]

I agree that rewriting the autogen system is not what we want. Still, we can get a nicer looking documentation with it. I've created a rtfd branch with sphinx configuration and a couple of pages (both generated and hand-written), and setup readthedocs.org project. The result may be observed here: http://ev3dev-lang.readthedocs.org.

What do you think?

[ddemidov]

Just for comparison, here is the same site with native readthedocs theme: http://ev3dev-lang.readthedocs.org/en/rtfd-native-theme/

[ddemidov]

@rhempel did some comments on the commit, I'll copy those here for the record:

@rhempel:
This looks quite interesting!

@ddemidov:
do you mean readthedocs theme, or the general reference docs?

@rhempel:
Both - I looked at the output of this effort and it's very attractive. Without having too close a look just yet, I am hoping that we'll be able to use this documentation framework to generate language specific examples of each API, and also a language specific overview of how the API fits in with the best practices for that language. It's not just a collection of objects and methods :-)

[ddemidov]

@rhempel, I think language-specific API reference and examples should go into language-specific repositories, especially since we did the complete decentralization of this repo.

[BertLindeman]

For me (amateur fiddler) the step from the API-spec to what exactly should I type-in for say python objects, always is a step I miss in the doc. Oke there is a motor example, that's fine, but
what should I specify to get e.g. the EV3-color-sensor in get-color mode. Not easily found, I think.
So language-specific doc would be a big help. (For the time being I keep myself at bash 😄 )

[ddemidov]

So language-specific doc would be a big help

I agree, but I still think that the best place for language-specific doc is the language-specific repo. That way the doc could be tailored to the specific language, use its common patterns, strong sides, etc, etc. For example, python has its own version of the specification together with some examples here: http://python-ev3dev.readthedocs.org/ (this is not to say that it could not be improved).

[BertLindeman]

No problem from me about WHERE the specification should be. It should just be "simply" pointing from the specification to the language-specific doc. I like the way the specification is split-up into separate paragraphs contrary to one large page. That is a huge improvement. Easier to find what you are looking for.

[ddemidov]

It should just be "simply" pointing from the specification to the language-specific doc.

I think sphinx/readthedocs allows to hierarchically combine docs from several projects, we could look into that.

I like the way the specification is split-up into separate paragraphs contrary to one large page. That is a huge improvement. Easier to find what you are looking for.

It also has a search, an index, and a per-page drop-down menu in the top bar :). I agree, its much easier to navigate around.

[ddemidov]

http://read-the-docs.readthedocs.org/en/latest/faq.html#how-do-i-host-multiple-projects-on-one-cname

[WasabiFan]

What do you think?

I like it! If you're willing to set it up, I'm sure I can look through it to figure out how it works and help maintain/update it.

Basically, you're doing the same thing that we were doing with the markdown file, but using reStructuredText syntax and publishing to the other site?

[ddemidov]

I've created #148, please look there for implementation details.

[ddemidov]

I've added description of the special sensor classes to the documentation in 7f9cc7f: http://ev3dev-lang.readthedocs.org/en/latest/sensors.html

[WasabiFan]

Thanks! And It looks great -- much better than a plain markdown doc!

[ddemidov]

I've added the python-ev3dev documentation project as a subproject of this repo on readthedocs. It now may be accesses both from its own url (http://python-ev3dev.readthedocs.org/) and at http://ev3dev-lang.readthedocs.org/projects/python-ev3dev/. When/if @rhempel merges ev3dev/ev3dev-lang-python#119, this will feel more natural, and we could link to the subproject docs from inside our main doc. What do you think of this?

[WasabiFan]

What do you think of this?

Sounds good to me. Mention me in the commit message or comment here to notify me when you add the link; I'll take a look and do the same for JS.

[ddemidov]

What would be the best place to put the link to? In the list of supported languages in README?
Something like this?

• Python (documentation)

I also thought of adding a drop-down menu to the navbar, but I have no idea of how to do this. Do you?

[ddemidov]

I made an attempt at changing the navbar to add the dropdown menu with libraries in 8a1c88d. The result is at http://ev3dev-lang.readthedocs.org/en/link-to-libs/. The need to replace the navbar template (and change it directly to add another library) feels ugly to me though.

[ddemidov]

I am leaning to a simple solution though. That is, just put a link to each library documentation in the main README.

[rhempel]

I'm back from a family weekend now, I'll look at outstanding PRs here, and then get back to the tacho driver updates.

[WasabiFan]

@ddemidov Sorry, looks like I forgot to respond to your comment above on the library links and I see that that linked commit is still outstanding. I'll leave it to your judgement on what you think is best; If you'd like to merge that branch, go ahead, or if you'd rather go with the README option I can do what I need to on my end.

[WasabiFan]

I think I'm going to hold off on adding the extra info to the spec to make the human-readable one complete until we land #152 because there are enough large changes over there that I'd rather not have to deal with merge conflicts.

[ddemidov]

I'll leave it to your judgement on what you think is best;

I think we should leave it as it is now (links in the main document). I don't want to mess with the theme templates too much.