ooc-dev team mailing list archive

[Scott Olson <scott@xxxxxxxxxxxxxxx>]

I agree with Noel.

On Friday 09 July 2010 04:29:43 Noel Cower wrote:
> 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