Generate erldocs or better + upload to devdocs.io for significant basho projects

[ghost]

Weekly meeting conversation point :

So - after getting involved in a conversation with @Licenser I decided I wanted to learn more about Riak AAE. It's always been a bit vague, and I know that most people just resort to reading the source code. But the source code commenting is gray, and fairly tiresome to read through.

And just like that, a happy thought coalesced in my mind. I thought, "wouldn't it be nice if there were some Edoc (even thought the font/color are horrible and it looks very 1990) generated docs somewhere so I could explore the AAE modules, API, and implementation more easily?"

Indeed! And some Basho staff appeared to have already thought a very similar thought - I quickly found the following resources, but they appear to be fairly old (riak_core) there's no site index of any sort, and there doesn't seem to be any generated docs for riak_kv:

• http://basho.github.io/riak-erlang-client/
• http://basho.github.io/riak_core/

Indeed. And they were much better to read than the documentation - despite the fact they were designed with a frameset (consequently making them un-linkable, how very 90s).

Hyperlinkable documentation never seemed to be a priority for Basho, that aspect of the semantic hypertext revolution having seemed to have largely passed them by.

For the documentation builds it might be nice if we could do something with a docker build in the same manner as The Beam Book so people don't need to splat a load of scripts all over their system in order to generate this stuff.

So, in summary, this ticket is to generate effective, functional API documentation, and get them included into devdocs.io.

[jadeallenx]

edoc is terrible it's true - what is this devdocs and how does it translate edoc into something that doesn't suck?

[ghost]

I suspect devdocs is related to the application Dash.

They set up some ruby based scrapers that pull down nicely formatted docs websites, or at least reasonably well behaved docs websites like the Erlang stdlib docs.

Lots of developers use devdocs.io because it doesn't make the eyes bleed and provides fast offline and online docs searching (try it, just hit the tab key to hit the search prompt).

It's also much nicer than having to run a google search every time you want to look something up in the docs (gets very tiring), and supports offline storage and searching so you can continue looking up docs even when you're offline, on the train of aeroplane.

It's open source, and documentation is typically added by means of someone creating a pull request with some parser changes - here's an example P/R where Erlang docs were added.

Does that make sense ?

[jadeallenx]

Thanks for the details!

I am asking because I too hate edocs formatting and I was curious how other people have tackled the problem of making edocs suck less. I have a lot of caremad about it.

Inside Basho we used to have "code study sessions" once a week where some sucker - er I mean, volunteer would walk people through a riak code path. We had sessions about get and put and the various finite state machines surrounding coverage.

It wouldn't take too much effort to resurrect that effort with a zoom or webinar or something like that.

[ghost]

Nice idea @mrallen1 - I'd definitely open the idea of study sessions as a separate ticket though - this is just narrowly focused on being able to read and navigate the edoc stuff without complete horrorshow :-) But yes, the knowledge needs to be refined and kept alive.