ooc-dev team mailing list archive

[Mark Fayngersh <phunny.phacts@xxxxxxxxx>]

As far as beauty goes, railsapi.com style is looking very good in terms of
color and simplicity.

On Sun, Jul 11, 2010 at 8:18 PM, Amos Wenger <amoswenger@xxxxxxxxx> wrote:

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


-- 
~phunny.phacts@xxxxxxxxx
~marfay@xxxxxxxxxxxx