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.