← Back to team overview

ooc-dev team mailing list archive

Our documentation system


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 :)



Follow ups