Hello,
I’m trying to create a workflow to make documentation easy.
I’ve dig google, the old haxe forum (nothing on the new website) and this forum…
Lots of pieces around, but nothing complete.
I don’t have HAXEDOC in my /usr/bin (was this tool dropped? is there a way to get it?)
so I’ve chosen DOX ( http://github.com/dpeek/dox ) which is not too bad actually.
The first step is creating the XML file.
The only way I’ve found working is putting an haxeflag in my project.xml
<haxeflag name="-xml" value="bin/doc.xml" />
and then launch
lime build neko
this make the file doc.xml
I’ve tried
lime build neko -xml bin/doc.xml
but it says
Error: You must have a “project.xml” file or specify another valid project file when using the ‘build’ command
I’ve tried haxe with a docs.hxml but that way I can document only the haxe library, nothing mine. if I specify the -cp src and -lib openfl -lib lime it doesn’t work)
The second step is compiling with dox
I launch
haxelib run dox -i bin -o docs
and it works perfectly
but I find documentation compiled for EVERY class in haxe and openfl (and obviously every other haxelib included in my project)
So,
what is your workflow to make documentation?
Because right now I can’t figure it out how to build an xml with ONLY my package.
The haxedoc tool was drop, since haxe 3 or 3.1 I think, and it doesn’t work with the latest versions,
but dox is great, and it’s the only documention tool maintained as far as I know.
You can use the dox option -in my.package to get only the doc for your project, if you put your code in a package.
Thank you @ibilon, this was exactly what I was looking for. I read the help print in dox but I didn’t understand these lines where talking about the packages
[-in | --include] <regex> : Add a path include filter
[-ex | --exclude] <regex> : Add a path exclude filter
In the end I’m doing like this
Workflow
make xml files
lime build neko --haxeflag='-xml bin/doc.xml'
make html documentation
haxelib run dox -i bin -o docs -in com
But there is something else I don’t understand.
The class I’m trying to document is called com.akifox.transform.Transformation
If I write dox [...] -in com it works (only the com tree is included)
but if I specify dox [...] -in com.akifox nothing get processed
why?
I want to document only THAT tree, no all the COM tree (which can contain other stuff).
Any idea?
The XML argument is not supposed to accept a path:
openfl build neko -xml
Depending on the platform you are building, it will put the file in “Export//types.xml”, which could be used elsewhere. Since Dox does the platforms based upon the file name, perhaps this should be “Windows.xml” instead of types.xml
Another idea would be to add Dox support to the new openfl deploy command:
Thank Joshua for the answer,
Now I understand why lime build neko -xml [path] was not working.
My fault I didn’t read the help but I’ve just assumed it was the same as haxe
Basically right now I am using this method:
The script gen_doc.sh removes all the files from the XML folder and the DOCS folder (the one which will receive the dox ed html files)
then it runs the compilation on every platform using gen_doc.hxml
and in the end runs dox with input the XML folder and output the DOCS folder.
It is quite good like this (tell me if I could improve it, as a newbie I am trying to make the things work, but for sure I will not find the best way at first try), the only problem is about the -in parameter in dox
I don’t know how to include only the package in a depth level higher than one
As I said something like -in openfl works, but not -in openfl.display.
Ideas?
PS: maybe this is stupid but can I ask you if is there any difference if I use the command openfl or lime? I can’t really see any difference. I know the difference between lime and openfl, but not the difference in the CLI.
I’m not sure if I’ve gotten that to work. I filter based on top level packages, but I understand the issue
lime and openfl use the same Lime tool, openfl uses teal instead of green, it uses an “OpenFL” welcome message, and changes the implied behavior of things like lime create project MyProject vs. openfl create project MyProject. Largely, it’s about what comes most naturally to you
I’ve actually tried with the very OPENFL and OPENFL.DISPLAY for testing.
It doesn’t work.
I think it might be a bug. (or maybe I am using it wrong)
I’ve submitted an issue on the repository.
We will see if it’s me (most probably) or a real bug.