ooc-dev team mailing list archive

[Amos Wenger <amoswenger@xxxxxxxxx>]

I agree about the woes of rST (even though its advantages are overlooked -
and the problems of
Markdown<http://www.codinghorror.com/blog/2009/12/responsible-open-source-code-parenting.html>,
too)

I agree with the Javadoc/Doxygen-ish syntax mixed with Markdown for
formatting.

I agree that Sphinx, although being very complete in terms of features, has
a lacking documentation, and let's be
honest, it's a bit frightening for a documentation tool.

I'm not entirely happy either with the doc produced by Sphinx, e.g. on
http://docs.ooc-lang.org/
It just doesn't feel right to navigate. In that area, inspiration can (and
should) be drawn from
sources like the Factor docs: http://docs.factorcode.org/, and RailsApi.com
http://railsapi.com/doc/rails-v2.3.8/

As ooc-lang.org's redesign progress, we might even think of some level of
integration between the blogging/articles
feature of the website and the docs (e.g. dead easy linking) - I'm looking
forward to reading your ideas on that.

So basically here are the requirements for a new doc system:

   - Easy to use. It might even take a glob of .ooc files and call rock
   -backend=json itself, by default
   - Javadoc/Doxygen syntax with Markdown-improved (e.g. implicit URLs,
   etc.) for formatting
   - Beautiful. Doc is boring - if the generated doc is pretty enough that
   it makes someone *want* to read it - bingo.
   - Easy to navigate. Pretty much everything should be clickable. ooc code
   should be highlighted. (Opt-out) links to .ooc source files (colored
   versions, anchor links?)

Then again, let's not forget that the whole stack of tools Friedrich has
built is unmatched as of yet in terms of doc generator for ooc suitable for
the SDK. Hence, if someone can come up with a 'better' solution (as Nilium
suggested he could do), I'd happily adopt it, as long as it matches the
requirements above.


> 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
>
> _______________________________________________
> 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
>