ooc-dev team mailing list archive

[Wander Nauta <info@xxxxxxxxxxxxxx>]

Hi all,

I am currently working on a homebrew documentation solution (called
Herdscribe) that skips the sonofaj and sphinx parts entirely. I don't think
Herdscribe is really fit for documenting Rock's SDK (it was designed with
libraries and apps in mind), but I think y'all should know about it anyway
:)

Herdscribe is designed to be put in a Makefile and generate single-page
taupe HTMLs and single-file OpenOffice/MS Office documents, all in a
convention-over-configuration manner. Herdscribe is focused on 'raw' API
documentation, but I'm planning on adding support for usefiles (for picking
up things like name, description and homepage of your project - zeroconf
yay) and Markdown (for adding 'plain text' documentation). From the inside,
it basically uses the new json parsing module to feed data to the Mustang
templating system.

Of course, like most everything I build, it's pretty messy and pre-pre-alpha
(it's not even on GitHub yet but I can push what I have if someone asks).

Wander Nauta (or partyfest if you prefer)

On Wed, Jul 7, 2010 at 16:31, Friedrich Weber <fred.reichbier@xxxxxxxxxxxxxx
> wrote:

> 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
>
> _______________________________________________
> Mailing list: https://launchpad.net/~ooc-dev
> Post to     : ooc-dev@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~ooc-dev
> More help   : https://help.launchpad.net/ListHelp
>