<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">On 09/11/2013 12:44 PM, Petr Vobornik
wrote:<br>
</div>
<blockquote cite="mid:523049A5.10208@redhat.com" type="cite">Hello,
<br>
<br>
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].
<br>
<br>
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.
<br>
<br>
You can see current state at my fedorapeople page [2].
<br>
<br>
I also converted 5 guides/articles which I wrote some time ago.
Guides are also part of the JSDuck app [3].
<br>
<br>
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.
<br>
<br>
Installation of JSDuck is documented on their page [4]. Basically
it requires ruby and JSDuck gem.
<br>
<br>
Usage:
<br>
$ cd install/ui/doc
<br>
$ make
<br>
<br>
Documentation is generated into: install/ui/build/code_doc
directory
<br>
<br>
[1] <a class="moz-txt-link-freetext" href="https://github.com/senchalabs/jsduck">https://github.com/senchalabs/jsduck</a>
<br>
[2] <a class="moz-txt-link-freetext" href="http://pvoborni.fedorapeople.org/doc">http://pvoborni.fedorapeople.org/doc</a>
<br>
[3] <a class="moz-txt-link-freetext" href="http://pvoborni.fedorapeople.org/doc/#!/guide">http://pvoborni.fedorapeople.org/doc/#!/guide</a>
<br>
[4] <a class="moz-txt-link-freetext" href="https://github.com/senchalabs/jsduck/wiki/Installation">https://github.com/senchalabs/jsduck/wiki/Installation</a>
<br>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
Freeipa-devel mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Freeipa-devel@redhat.com">Freeipa-devel@redhat.com</a>
<a class="moz-txt-link-freetext" href="https://www.redhat.com/mailman/listinfo/freeipa-devel">https://www.redhat.com/mailman/listinfo/freeipa-devel</a></pre>
</blockquote>
<br>
I looked into the documentation effort and (ruby dependency
discussion aside) I don't have any major objections. I like how the
generated pages look, and they are intuitive and easy to navigate.<br>
<br>
A couple of nitpicks:<br>
<br>
1) There are some spelling mistakes (e.g. <span class="com">Apllication_controller</span>)<br>
<br>
2) Bulleted lists are not rendered nicely in the html output (see
for example the doc string for _base.Builder property 'string_mode'.
I think a list needs to look like this in the source code:<br>
<br>
/**<br>
* This is a list:<br>
*<br>
* - 'element1'<br>
* - 'element2'<br>
*<br>
*/<br>
<br>
as opposed to this:<br>
<br>
/**<br>
* This is a list:<br>
* - 'element1'<br>
* - 'element2'<br>
*/<br>
<pre class="moz-signature" cols="80">--
Regards,
Ana Krivokapic
Associate Software Engineer
FreeIPA team
Red Hat Inc.</pre>
</body>
</html>