Documentation

[Nickolay Platonov]

Hello all,

I'd like to start the discussion about documentation.

Recently I published Test.Run on extjs-ux.org (this site was my early attempt to create something like JSAN, for ExtJS extensions)

Here is the documentation (received with ext-doc):
http://extjs-ux.org/ext-docs/?class=Test.Run


Pros for ext-doc:
- good-looking
- standardized sections (header, properties, methods, events)
- convenient to use (compacted descriptions, quick links in right-top corner, can hide inherited properties)

Cons:
- Hard-coded sections (can't create move aside from pre-defined template - it will be always header, config options, properties etc)
- raw HTML is using as text markup
- support only jsdoc format.

Considering the above, here is how I see the documentation system.

1. Abstract document model with a number of pre-defined elements, like 'header', 'paragraph', 'class', 'method', 'attribute' etc
2. Perhaps it can be made in OO way - for example 'method' isa 'paragraph' with special template.
3. Document model should allow to define new elements

Then:

sources -> abstract document model -> documentation in various formats
      parsers                  producers


Perhaps I've re-invent the bicycle )

Anyway - RFC

Regards, Nickolay

[David E. Wheeler]

On May 23, 2009, at 5:06 AM, Nickolay Platonov wrote:

> Perhaps I've re-invent the bicycle )
>
> Anyway - RFC

All I have to say is: MultiMarkdown++

Best,

David

[Nickolay Platonov]

On Sun, May 24, 2009 at 2:37 AM, David E. Wheeler <da...@justatheory.com> wrote:

All I have to say is: MultiMarkdown++

Ok, lets try to look from another side. If I have a parser from Markdown, how I can integrate it with my distribution?

Nickolay

[David E. Wheeler]

The `doc` action would need to be updated to look for Markdown
documentation and run it through Text::MultiMarkdown.

Best,

David

[Nickolay Platonov]

Aha.. Probably the parser class should be configurable.
I'll try to integrate jsdoc parser - will post here about results.

Nickolay