Dox - Haxe Documentation Generator

[Simon Krajewski]

Hi,

we just release Dox on haxelib. Dox is a documentation generator for
haxe which takes the output of a haxe -xml compilation and generates
template-based HTML pages.

The good news: Out of the box, the result looks like this:
http://dpeek.com/dox/
The bad news: You will probably need a haxe development build as there
were some XML generation issues in the haxe 3 release.

You can "haxelib install dox" right now and see the available command
line arguments using "haxelib run dox":

[-r | --document-root] <path> : Set the document root path
[-o | --output-path] <path> : Set the output path for generated pages
[-i | --input-path] <path> : Set the xml input path
[-t | --template-path] <path> : Add template directory
[-res | --resource-path] <dir> : Add a resource directory whose contents
are copied to the output directory
[-in | --include] <regex> : Add a path include filter
[-ex | --exclude] <regex> : Add a path exclude filter
[--title] <name> : Set the page main title

The default templates can be found at <haxelib
repository>/dox/<version>/templates and are compiled using a haxe port
of Motion Twin's templo engine:
http://haxe.org/com/libs/mtwin/templo

Let us know if there are questions or problems, our goal is to make this
into _the_ documentation generator for haxe. If you are interested in
contributing, check out the source code:
https://github.com/dpeek/dox

Enjoy!
Simon

[Jason O'Neil]

Cheers to Simon and David... a lot of work has gone into this and it's looking good!

I'll try get some of my libraries documented using this in the coming weeks and provide feedback.

Jason

Simon

--
To post to this group haxe...@googlegroups.com
http://groups.google.com/group/haxelang?hl=en
--- You received this message because you are subscribed to the Google Groups "Haxe" group.
For more options, visit https://groups.google.com/groups/opt_out.

[Dan Korostelev]

Hey. Thanks for such a good-looking documentation generator.

Could you please provide a noob-friendly "getting started" guide? For example, I only have code I've written and I don't know about XML's, ImportAll's and stuff and don't have time to grasp it. :)

It would be great to make it even simplier (like dox <source_roots> <output_dir>).

понедельник, 17 июня 2013 г., 18:20:07 UTC+4 пользователь Simon Krajewski написал:

[Simon Krajewski]

Am 17.06.2013 17:31, schrieb Dan Korostelev:
> Hey. Thanks for such a good-looking documentation generator.
>
> Could you please provide a noob-friendly "getting started" guide? For
> example, I only have code I've written and I don't know about XML's,
> ImportAll's and stuff and don't have time to grasp it. :)
>
> It would be great to make it even simplier (like dox <source_roots>
> <output_dir>).

It's a two step process:

1. let haxe generate .xml output
2. let dox consume these .xml files and generate pages

1. is done by adding -xml <output file> to your haxe command line. After
this, you can use dox's -i option to let it know where to find that .xml
file, e.g. -i ../yourProject/bin.

Simon

[tom rhodes]

sweet, how about comment style to add info to the docs? javadoc style comments or some other way?

Simon

[Simon Krajewski]

Am 17.06.2013 18:36, schrieb tom rhodes:
> sweet, how about comment style to add info to the docs? javadoc style
> comments or some other way?

We can add something like this later. At the moment everything is piped
through a markdown parser by default, but it's no problem to make this
configurable. So if someone has a Javadoc parser...

Simon

[Laurence Taylor]

Does it / could it support grouping by module? The Stax namespace looks fiendish when represented as classes in documentation.

regards,

Laurence

Simon

[Simon Krajewski]

Am 17.06.2013 21:06, schrieb Laurence Taylor:
> Does it / could it support grouping by module? The Stax namespace
> looks fiendish when represented as classes in documentation.

That's not supported or planned as it would require some extensive
restructuring. However, the output of -xml does have a "file" attribute
on each type, so it would be possible to group them on that and modify
dox/Generator.hx to use templates accordingly.

Simon

[David Peek]

Classdef/Typedef/etc have a module property we could use to group things like that.

Probably better to fork for your needs as it would be tricky to make an option.

David

[Fernando Serboncini]

I've tried to do it, but I couldn't manage to do it.

is it possible, for example, to generate a single dox output for everything under a particular directory (like /usr/lib/haxe/{std,lib}/ ) ?

[David Peek]

So, there are basically two steps tp generating your documentation:

First you need to generate xml for the types you want to document. This xml is generated by the compiler using the "-xml output.xml" argument. You should place this xml in a directory, named for the platform it is generated for. So, if you have a javascript library your command might look like this:

haxe -js api.js --no-output -xml api/js.xml --macro include('mylib')

No output prevents generation of the api.js file, and the macro call includes all the classes under the package 'mylib'. You could potentially generate a number of different platforms in this way (see gen.hxml - the ImportAll is specific to generating docs for the std library as there a number of special cases that need to be handled).

Once you have a folder of xml for each platform (api/js.xml, api/neko.xml etc) you can generate your docs with this command:

haxelib run dox -r /root -o output -i api

Where "/root" is the root of your documentation on the webserver, "output" is the directory to generate to, and "api" is the location of your xml files.

We might be able to refine this workflow to make it simpler, however there will always be special cases in the xml generation part.

Hope this helps,

David

[Jason O'Neil]

My experience:

• I needed a fairly recent haxe build (the nightly from a few weeks ago didn't cut it)
• The "--macro include()" for me bailed out with an unhelpful "File "interp.ml", line 186, characters 32-38: Assertion failed" - maybe I've got some dodgy code that got included?  I just used "-main MainClass" instead
• Dox happily compiled the HTML for both my client and server code bases
• Not everything was showing up in the filter on the left, but David fixed it in an update: `haxelib git dox https://github.com/dpeek/dox.git`
• After that, it's all working
  

Now that it's working, I'm amazed :)  "915 types in 121 packages" ... all documented!  That should make my life easier.

Can't wait to start adding these for each of my libraries.  I think it's worth adding support to lib.haxe.org also.

Thanks again,
Jason

[Matthew Spencer]

--macro include('...')
try 
--macro "include('...')"

--Matthew

[Jason O'Neil]

Ah, that does work.

Thanks for the tip!

[Matthew Spencer]

Out of curiosity, what shell are you using, and what was the exact line you ran?

[Jason O'Neil]

I'm using bash, and was building from a hxml file

haxe doc.hxml

The hxml was something like:

-lib lib1
-lib lib2
-cp src/

# Compile flags
-D client
-D embed_js
-D haxeJSON

-xml dox/js.xml
-js doc.js
#-main client.Client
--macro "include('client')"
--macro "include('tasks')"
--macro "include('app')"
--no-output

And then a "--next" and a similar setup for the neko.xml generation.

Jason

On Tue, Jun 18, 2013 at 12:40 PM, Matthew Spencer <m22sp...@gmail.com> wrote:

Out of curiosity, what shell are you using, and what was the exact line you ran?

--