On 09/12/2013 07:50 AM, Martin Kosek wrote:
On 09/11/2013 11:24 PM, Dmitri Pal wrote:
On 09/11/2013 12:28 PM, Simo Sorce wrote:
On Wed, 2013-09-11 at 12:44 +0200, Petr Vobornik wrote:
Hello,

This is a part of documentation effort which started couple month
ago.
Attached patches improves devel documentation of Web UI. Mostly by
annotating source code and then processing it by JSDuck tool[1].

The documentation is not complete - most plugins and member of some
core
widgets and facets are not annotated yet. I'm sending it now because
I
need to focus on more pressing tickets.

You can see current state at my fedorapeople page [2].

I also converted 5 guides/articles which I wrote some time ago.
Guides
are also part of the JSDuck app [3].

The idea is to regularly generate the doc and place it on
docs.freeipa.org (not in production at the moment) so all doc would
be
on one place.

Installation of JSDuck is documented on their page [4]. Basically it
requires ruby and JSDuck gem.

Usage:
$ cd install/ui/doc
$ make

Documentation is generated into: install/ui/build/code_doc directory

[1] https://github.com/senchalabs/jsduck
[2] http://pvoborni.fedorapeople.org/doc
[3] http://pvoborni.fedorapeople.org/doc/#!/guide
[4] https://github.com/senchalabs/jsduck/wiki/Installation

I would rather not grow a dependency on Ruby in the freeIPA project.
Are there any alternatives ?

Simo.

Is it dev side dependency? We might have issues if we need gems during
build process that are not a part of distro.

This a UI Doc building dependency, i.e. not needed when package is installed.
So someone/something doing a release and releasing the doc will need the ruby +
respective rubygem installed.

If we want to automate the build and let the doc be built for example on koji,
I am afraid we would have to step back from using jsDuck, or let Petr package
it in Fedora since he used it despite my previous warnings :-)

The question is if we want to include these docs into some freeipa-doc package. I don't think it's necessary. The important thing is to have it on the web.

Short overview of other JavaScript doc tools

JSDoc <https://github.com/jsdoc3/jsdoc> <http://usejsdoc.org/>
- runs on rhino or can be downloaded by npm
- doc comments need to be too verbose (problems with introspection of old class system) - output is much worse then jsduck (can't find online example, the one which I generated is already gone)
- slow

ScriptDoc/AjaxDoc http://ajaxdoc.codeplex.com/
- requires .NET

YUIDoc http://developer.yahoo.com/yui/yuidoc/
- requires node.js
+ nice output <http://yuilibrary.com/yui/docs/api/classes/Graph.html>
- doesn't do code introspection - every information has to be in doc comment

NaturalDocs http://www.naturaldocs.org/
+ packaged
- only basic JavaScript support (no code introspection)
- don't like the output <http://people.apache.org/~jkuhnert/>

Doxygen
+ packaged (not sure about JS support)
- the output is pretty bad <http://jsunit.berlios.de/classes.html>

Dojo Doc
- output requires php
+ nice output <https://dojotoolkit.org/api/>
~ not sure about code introspection, most likely works only with Dojo classes

JSDuck
- ruby
+ IMO best output
+ sufficient code introspection - Works with older and new code
+ fast (compare to JSDoc)


Subjective comparison in specific areas:

- Writing doc comments:
  JSDuck > YUIDoc | DojoDoc | NaturalDocs > JSDoc > Doxygen

- Output (UX)
  JSDuck > YUIDoc | DojoDoc > NaturalDocs > JSDoc > Doxygen

- Packaging
  NaturalDocs | Doxygen > JSDuck | YUIDoc > JSDoc > DojoDoc



Petr, we should think if we should keep UI doc and articles in devel repo or if
leave just the anonated code there and move all development articles and guides
to our new doc repo
http://www.freeipa.org/page/Contribute/Documentation
Martin


The move can be considered only if we want to package the code doc. And we might then require freeipa repo for doc generation which is not good.

To avoid it we would have to remove guides from the output app. It's bad because it would break or make more difficult links from code [1] to guides and vice versa.

[1] https://github.com/senchalabs/jsduck/wiki/%40aside
--
Petr Vobornik

_______________________________________________
Freeipa-devel mailing list
Freeipa-devel@redhat.com
https://www.redhat.com/mailman/listinfo/freeipa-devel

Reply via email to