ooc-dev team mailing list archive

[Friedrich Weber <fred.reichbier@xxxxxxxxxxxxxx>]

Hi all,

there was some discussion going on in #ooc-lang about the documentation 
system we're using and going to use. Since we need a fast and definite 
decision about an important topic, I'm now going to move the discussion 
to the mailing list :P

Our current documentation system works like this:

1) The developer documents his code via oocdoc comments.
2) The compiler exports API information containing oocdocs via the JSON 
backend (http://docs.ooc-lang.org/compilers/json.html) -- I'm currently 
finishing rock's implementation of the JSON backend.
3) sonofaj (http://github.com/fredreichbier/sonofaj) is used to convert 
the JSON data to a bunch of sphinx (http://sphinx.pocoo.org) - 
compatible .rst files. I've developed a sphinx extension to support 
oocisms (so you can write :cover:`Int` and link to the Int cover 
directly, for example)
4) These .rst files are integrated into the ooc-docs 
(http://github.com/nddrylliog/ooc-docs) repository
5) sphinx is used to generate the hand-written *and* API documentation 
(where the result is http://docs.ooc-lang.org)

I know this is a rather complicated workflow, though steps 2-5  can be 
automated and in fact are automated currently: After a commit to the 
bootcamp (http://github.com/ooc/bootcamp) or ooc-docs repo, a 
post-commit hook regenerates the documentation at docs.ooc-lang.org.

However, since we're fast moving to using rock as the default compiler, 
the API docs are a bit outdated now -- rock uses its own sdk. So, this 
workflow (mostly the sonofaj part, since the JSON spec needed to be 
updated to support all those awesomities brought by rock) would need a 
bit of polishing and simplification (what I'd do).

Sooo, now there were some voices in the IRC channel stating their 
dislike of sphinx and reStructuredText. I'm now wondering if we should 
keep the described approach or if we should move to a new (possibly 
homebrew) approach, so *I want your opinions!* ;-)

I'm a bit biased here because I like rst and sphinx very much and I've 
implemented most of the stuff above -- but I want to give you some brain 
impulses anyway ;-)

Our primary goal should be getting nice documentation done nicely as 
fast and complete as possible - since without documentation, we're 
doomed. :D
I think the biggest advantage of the sphinx approach is: It works and 
it's really powerful. Documentation doesn't only consist of API 
documentation, a really really great percentage should consist of 
hand-written documentation (and I'm not speaking of tutorial-style 
documentation like beutdeuce's cool ooc (which is awesome btw)) -- and 
sphinx could handle both of them. Its really primarily designed for 
hand-written documentation, but it works with API documentation nicely 
anyway - well, in my opinion. ;)
Of course, it's not desirable to only get documentation done as fast as 
possible, we should also be happy with it (<3): Our developers should 
*want* to write documentation, and so it's important to choose a default 
workflow that is loved by everyone (or, rather, most people). Seems like 
sphinx doesn't seem to be loved much, we should probably move to 
something else. IMO, it's a bit sad to abandon the workflow above, but 
I'd be okay with that, we should take the pragmatic road, shouldn't we? :D
But if we are going to move to something else -- what do we move to? And 
how do we handle hand-written and automatically generated documentation 
nicely?
Sure, rst is rather quirky to use at the beginning, but it's also very 
powerful. I think the rst critics need to decide if their rst criticism 
is deep or serious enough to "justify" a homebrew documentation 
solution. If it really is, I'm fine with it ;-) Again, our goal is to 
get nice documentation nicely.

So, just my two eurocents, I'm eager to hear your opinions now :)

Cheers,

Friedrich