Proposal new documentation template / system

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Proposal new documentation template / system

Juan Delgado
Hi again : )

I think there's a general consensus that the current documentation can
be improved from a pure technical point of view. For example, making
the package tree persistent when going backwards and forwards:

http://code.google.com/p/haxe/issues/detail?id=57

When preparing the documentation for XAPI I realized that the output
from haxedoc is not really functional on its own. For example, it
misses the JS file that toggles on/off the tree, so if you click the
package name, you get a JS error. Also there's no styles, etc. Having
said that, what has surprised me is how automatically integrates with
haXe's website. If anyone missed it from my previous post, check it
out:

http://lib.haxe.org/d/xapi/0.1/

That documentation comes directly from my code and appears on the
website automatically if you place your haxedoc.xml file correctly
when you submit to haxelib. That is very nice indeed.

So, if you ask me what the perfect doc system should have, I'd say:

- 100% functional by default.
- Simple, but moderately good looking by default.
- Easy to style (tweak some colours, add an icon, page footers, copyright, etc).
- Easy to skin (come up with a totally different output, not sure if
HTML only or even things like PDF/chm as well).

Once we agree on the big picture we can go down to the nitty-gritty
like frames/no frames, HTML markup, etc.

I'm happy to take such a project improving haxedoc if Nicolas thinks
it's a good idea.

Anybody interested to contribute with actual coding or suggestions is
more than welcome : )

Let me know,

Juan

--
Juan Delgado - Zárate
http://zarate.tv
http://blog.zarate.tv

--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Proposal new documentation template / system

Nicolas Cannasse
Juan Delgado a écrit :

> Hi again : )
>
> I think there's a general consensus that the current documentation can
> be improved from a pure technical point of view. For example, making
> the package tree persistent when going backwards and forwards:
>
> http://code.google.com/p/haxe/issues/detail?id=57
>
> When preparing the documentation for XAPI I realized that the output
> from haxedoc is not really functional on its own. For example, it
> misses the JS file that toggles on/off the tree, so if you click the
> package name, you get a JS error. Also there's no styles, etc. Having
> said that, what has surprised me is how automatically integrates with
> haXe's website. If anyone missed it from my previous post, check it
> out:
>
> http://lib.haxe.org/d/xapi/0.1/
>
> That documentation comes directly from my code and appears on the
> website automatically if you place your haxedoc.xml file correctly
> when you submit to haxelib. That is very nice indeed.
>
> So, if you ask me what the perfect doc system should have, I'd say:
>
> - 100% functional by default.
> - Simple, but moderately good looking by default.
> - Easy to style (tweak some colours, add an icon, page footers, copyright, etc).
> - Easy to skin (come up with a totally different output, not sure if
> HTML only or even things like PDF/chm as well).
>
> Once we agree on the big picture we can go down to the nitty-gritty
> like frames/no frames, HTML markup, etc.
>
> I'm happy to take such a project improving haxedoc if Nicolas thinks
> it's a good idea.
>
> Anybody interested to contribute with actual coding or suggestions is
> more than welcome : )

Hi Juan,

You can have a look at how it's done by haxelib by reading
haxe/std/tools/haxelib/Site.hx (fillContent "d")

haxe.org have its own printer which differ from haxedoc one since it
produces Wiki syntax and not HTML :
https://svn.motion-twin.com/hxwiki/v2/src/tools/ApiSync.hx

Best,
Nicolas


--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Proposal new documentation template / system

Robert Sköld
Speaking of documentation, would it be hard to get the method documentation to link to the source of it. Most of the times I need to have a look in the source code anyway and having it in the api listing would be very helpful to understand what some methods do. Similar to these perhaps? Date

I had a brief look in the source and it's all based on XMLs, right? I'm guessing those XMLs does not contain a copy of the source to link to?

Just an idea anyway :)

Cheers!

On Feb 13, 2010, at 18:43 , Nicolas Cannasse wrote:

Juan Delgado a écrit :
Hi again : )
I think there's a general consensus that the current documentation can
be improved from a pure technical point of view. For example, making
the package tree persistent when going backwards and forwards:
http://code.google.com/p/haxe/issues/detail?id=57
When preparing the documentation for XAPI I realized that the output
from haxedoc is not really functional on its own. For example, it
misses the JS file that toggles on/off the tree, so if you click the
package name, you get a JS error. Also there's no styles, etc. Having
said that, what has surprised me is how automatically integrates with
haXe's website. If anyone missed it from my previous post, check it
out:
http://lib.haxe.org/d/xapi/0.1/
That documentation comes directly from my code and appears on the
website automatically if you place your haxedoc.xml file correctly
when you submit to haxelib. That is very nice indeed.
So, if you ask me what the perfect doc system should have, I'd say:
- 100% functional by default.
- Simple, but moderately good looking by default.
- Easy to style (tweak some colours, add an icon, page footers, copyright, etc).
- Easy to skin (come up with a totally different output, not sure if
HTML only or even things like PDF/chm as well).
Once we agree on the big picture we can go down to the nitty-gritty
like frames/no frames, HTML markup, etc.
I'm happy to take such a project improving haxedoc if Nicolas thinks
it's a good idea.
Anybody interested to contribute with actual coding or suggestions is
more than welcome : )

Hi Juan,

You can have a look at how it's done by haxelib by reading haxe/std/tools/haxelib/Site.hx (fillContent "d")

haxe.org have its own printer which differ from haxedoc one since it produces Wiki syntax and not HTML :
https://svn.motion-twin.com/hxwiki/v2/src/tools/ApiSync.hx

Best,
Nicolas


--
haXe - an open source web programming language
http://haxe.org


--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Proposal new documentation template / system

Juan Delgado
Nice one Robert.

haxedoc.xml actually has information about in which line each method
is, so it's in theory possible.

Added to the wish list : )

J

2010/2/13 Robert Sköld <[hidden email]>:

> Speaking of documentation, would it be hard to get the method documentation
> to link to the source of it. Most of the times I need to have a look in the
> source code anyway and having it in the api listing would be very helpful to
> understand what some methods do. Similar to these perhaps? Date
> I had a brief look in the source and it's all based on XMLs, right? I'm
> guessing those XMLs does not contain a copy of the source to link to?
> Just an idea anyway :)
> Cheers!
> On Feb 13, 2010, at 18:43 , Nicolas Cannasse wrote:
>
> Juan Delgado a écrit :
>
> Hi again : )
>
> I think there's a general consensus that the current documentation can
>
> be improved from a pure technical point of view. For example, making
>
> the package tree persistent when going backwards and forwards:
>
> http://code.google.com/p/haxe/issues/detail?id=57
>
> When preparing the documentation for XAPI I realized that the output
>
> from haxedoc is not really functional on its own. For example, it
>
> misses the JS file that toggles on/off the tree, so if you click the
>
> package name, you get a JS error. Also there's no styles, etc. Having
>
> said that, what has surprised me is how automatically integrates with
>
> haXe's website. If anyone missed it from my previous post, check it
>
> out:
>
> http://lib.haxe.org/d/xapi/0.1/
>
> That documentation comes directly from my code and appears on the
>
> website automatically if you place your haxedoc.xml file correctly
>
> when you submit to haxelib. That is very nice indeed.
>
> So, if you ask me what the perfect doc system should have, I'd say:
>
> - 100% functional by default.
>
> - Simple, but moderately good looking by default.
>
> - Easy to style (tweak some colours, add an icon, page footers, copyright,
> etc).
>
> - Easy to skin (come up with a totally different output, not sure if
>
> HTML only or even things like PDF/chm as well).
>
> Once we agree on the big picture we can go down to the nitty-gritty
>
> like frames/no frames, HTML markup, etc.
>
> I'm happy to take such a project improving haxedoc if Nicolas thinks
>
> it's a good idea.
>
> Anybody interested to contribute with actual coding or suggestions is
>
> more than welcome : )
>
> Hi Juan,
>
> You can have a look at how it's done by haxelib by reading
> haxe/std/tools/haxelib/Site.hx (fillContent "d")
>
> haxe.org have its own printer which differ from haxedoc one since it
> produces Wiki syntax and not HTML :
> https://svn.motion-twin.com/hxwiki/v2/src/tools/ApiSync.hx
>
> Best,
> Nicolas
>
>
> --
> haXe - an open source web programming language
> http://haxe.org
>
>
> --
> haXe - an open source web programming language
> http://haxe.org
>



--
Juan Delgado - Zárate
http://zarate.tv
http://blog.zarate.tv

--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Proposal new documentation template / system

Juan Delgado
Hi,

Nicolas, do you think you could add to the generated haxedoc.xml
output not only the line in which a method is declared, but also in
which line it ends? That would make implementing Robert's suggestion
much easier.

I've been looking at genxml, and I can see where you create the line
attribute, but looking at the lexer class I'm not sure where's the
info we need.

Thanks,

Juan

On Sat, Feb 13, 2010 at 6:19 PM, Juan Delgado <[hidden email]> wrote:

> Nice one Robert.
>
> haxedoc.xml actually has information about in which line each method
> is, so it's in theory possible.
>
> Added to the wish list : )
>
> J
>
> 2010/2/13 Robert Sköld <[hidden email]>:
>> Speaking of documentation, would it be hard to get the method documentation
>> to link to the source of it. Most of the times I need to have a look in the
>> source code anyway and having it in the api listing would be very helpful to
>> understand what some methods do. Similar to these perhaps? Date
>> I had a brief look in the source and it's all based on XMLs, right? I'm
>> guessing those XMLs does not contain a copy of the source to link to?
>> Just an idea anyway :)
>> Cheers!
>> On Feb 13, 2010, at 18:43 , Nicolas Cannasse wrote:
>>
>> Juan Delgado a écrit :
>>
>> Hi again : )
>>
>> I think there's a general consensus that the current documentation can
>>
>> be improved from a pure technical point of view. For example, making
>>
>> the package tree persistent when going backwards and forwards:
>>
>> http://code.google.com/p/haxe/issues/detail?id=57
>>
>> When preparing the documentation for XAPI I realized that the output
>>
>> from haxedoc is not really functional on its own. For example, it
>>
>> misses the JS file that toggles on/off the tree, so if you click the
>>
>> package name, you get a JS error. Also there's no styles, etc. Having
>>
>> said that, what has surprised me is how automatically integrates with
>>
>> haXe's website. If anyone missed it from my previous post, check it
>>
>> out:
>>
>> http://lib.haxe.org/d/xapi/0.1/
>>
>> That documentation comes directly from my code and appears on the
>>
>> website automatically if you place your haxedoc.xml file correctly
>>
>> when you submit to haxelib. That is very nice indeed.
>>
>> So, if you ask me what the perfect doc system should have, I'd say:
>>
>> - 100% functional by default.
>>
>> - Simple, but moderately good looking by default.
>>
>> - Easy to style (tweak some colours, add an icon, page footers, copyright,
>> etc).
>>
>> - Easy to skin (come up with a totally different output, not sure if
>>
>> HTML only or even things like PDF/chm as well).
>>
>> Once we agree on the big picture we can go down to the nitty-gritty
>>
>> like frames/no frames, HTML markup, etc.
>>
>> I'm happy to take such a project improving haxedoc if Nicolas thinks
>>
>> it's a good idea.
>>
>> Anybody interested to contribute with actual coding or suggestions is
>>
>> more than welcome : )
>>
>> Hi Juan,
>>
>> You can have a look at how it's done by haxelib by reading
>> haxe/std/tools/haxelib/Site.hx (fillContent "d")
>>
>> haxe.org have its own printer which differ from haxedoc one since it
>> produces Wiki syntax and not HTML :
>> https://svn.motion-twin.com/hxwiki/v2/src/tools/ApiSync.hx
>>
>> Best,
>> Nicolas
>>
>>
>> --
>> haXe - an open source web programming language
>> http://haxe.org
>>
>>
>> --
>> haXe - an open source web programming language
>> http://haxe.org
>>
>
>
>
> --
> Juan Delgado - Zárate
> http://zarate.tv
> http://blog.zarate.tv
>



--
Juan Delgado - Zárate
http://zarate.tv
http://blog.zarate.tv

--
haXe - an open source web programming language
http://haxe.org