ooc-dev team mailing list archive

[Noel Cower <ncower@xxxxxxxxx>]

I'm personally in the opposed-to-reStructuredText-in-specific (I'll refer to
the format as rst from now on) camp.  I don't know why people use it or why
they think it's nice, although it appears Python users are the only group
who like it (there's a joke to be made here, but I'm too tired to do it).

My biggest problems with it are, firstly, that it's ugly.  I don't think
I'll bother qualifying this since what I think is ugly is what others
(Python users) think is pretty.  That being said, finding rst pretty
probably makes you defective.  I tried to like it, but I just can't do it.

Secondly, rst is not common.  As I mentioned before, this is a Python thing,
Sphinx appears to be a Python thing as well, and while I'm sure it's going
great for them (I'm not a big fan of their documentation though), I don't
think this is going to be even one bit endearing to people who don't use
Python.  Most people, I think, are familiar with the Javadoc (or Doxygen)
style documentation comment formatting, if any at all, and that's what I
think we should be using - preferably some hybrid of Javadoc style comments
with Markdown for formatting, because Markdown is easy to use and there are
existing implementations for just about everything.

Thirdly, I tried to find reference material for Sphinx and how I ought to
write documentation for it, but, to be honest their, documentation sucks so
much that I couldn't find anything useful, and I'm not going to go digging
around in Python source code for real examples when I don't understand
Python well enough to figure it out.  My personal opinion is that if I can't
figure out how to write documentation based on Sphinx's own documentation,
then I'm not doing it.

So, a home-grown solution is probably the best bet (for Javadoc style
comments), at least in my book.  Either that or we can try to hack ooc
support into something else, or use Sphinx without using rst (I doubt this
is possible).

All that said, I will be using Javadoc-style comments in my own code from
now on.  Whatever ends up happening with doc comments, if it doesn't fit my
own documentation style, I'll just write my own tools, since my code won't
affect anyone else's code.  Wouldn't be the first time I've written a
documentation generator, and given that we have the json output from rock,
it would probably be the first time writing such a tool would actually be
easier (parsing closed-source proprietary BASIC variants to extract doc
comments/structure is *not* fun).

As usual, I don't know if the above will make any sense.

-noel

On Wed, Jul 7, 2010 at 7:31 AM, 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
>