Author: sebastien.lelong
Date: Sun Sep 7 00:53:39 2008
New Revision: 291
Added:
wiki/JalapiWelcome.wiki
Log:
jalapi welcome + howto page
Added: wiki/JalapiWelcome.wiki
==============================================================================
--- (empty file)
+++ wiki/JalapiWelcome.wiki Sun Sep 7 00:53:39 2008
@@ -0,0 +1,96 @@
+#summary jalapi, the jallib API documentation
+#labels Type-Jalapi,Phase-Support
+
+= What is jalapi =
+
+*jalapi* is the jallib API documentation. You access jalapi from here:
+
+ * [http://jallib.googlecode.com/svn/trunk/unvalidated/doc/html/index.html
jalapi for unvalidated map]
+
+ * _jalapi for validated map_ (available soon)
+
+
+*jalapi* is directly integrated to jallib's SVN repository. You can also
have access to jalapi while downloading a jallib package.
+
+
+= jalapi for developers =
+
+== Description ==
+
+*jalapi* documentation is generated from the comments found on jal
libraries, particularly from:
+
+ * [JallibStyleGuide JSG] headers. A library must be strictly
[JallibStyleGuide JSG] compliant before being integrated to jalapi.
+
+ * comments found directly above `var`, `const`, `procedure` and
`function`.
+
+== How to write comments ==
+
+The two following examples show how to comment correctly your code so
*jalapi* can extract them.
+
+*good*
+{{{
+
+-- this my procedure
+-- it's amazing !
+procedure my_proc() is
+end procedure
+}}}
+
+*bad*
+{{{
+-- this is still my procedure
+
+-- it's not that amazing
+procedure my_proc() is
+end procedure
+}}}
+
+
+On the second example, only the very first line above the procedure will
considered as doc, because there's an empty line. That is, *jalapi* the
whole comment block above, until it finds an empty line.
+
+== About syntax... ==
+
+*jalapi* is also converting your comments in html, following the Google
Code Wiki Markup Syntax. That is, you can add bullet list, tables, etc...
just you'd do here, in a wiki page. _But_, while GC wiki doesn't respect
line feeds (or carriage return), *jalapi* tries to keep your carriage
return: when there's a "`\n`", it produces an "`<br/>`" html element.
+
+Finally, keep in mind the following rules: _don't make too fancy
comments_. While this sounds beautiful in your code (though it can be heavy
to read), it'll be converted to html, and this can sometime produces weird
things. So, avoid writing long dashes lines to separate your block, etc...
+
+*Keep it simple !*
+
+
+== Howto generate doc ==
+
+There are two main scripts to generate your documentation. Both can only
be run from Linux, because they uses `grep`, `sed`...
+
+=== jalapi.py ===
+
+`jalapi.py` takes a template and a jal file as inputs. It also needs
`SAMPLEDIR` environment variable to be defined. It prints the html result
on stdout.
+
+Ex
+{{{
+cd ..../tools
+SAMPLEDIR=../unvalidated/sample python jalapi.py jalapi_html.tmpl
mylib.jal > mylib.html
+}}}
+
+Since html files are directly integrated to SVN, and served by GC apache
server, you need to adjust the mimetype of generated files, so
there're "real" html files, and not just raw ascii text (it won't display
correctly if you don't do this):
+
+{{{
+svn propset svn:mime-type text/html mylib.html
+}}}
+
+
+=== jalapi_generate.sh ===
+
+Because all of this can be a real p.i.t.a, there's another script gluing
the whole, which automatically generate documentation for all *libraries*
found, *except device files*. (device files are not considered because
there's no such comments in code, this generates a lot of duplicate
information)
+
+Running this script is simple as:
+
+{{{
+cd ..../tools
+./jalapi_generate.sh path/to/validated/or/unvalidated
+}}}
+
+That is, it takes a path to either `validated` or `unvalidated` map. It
automatically find libraries, sets SAMPLEDIR, add files to the `doc/html`
directory and correctly set SVN properties.
+
+
+
+
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"jallib" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/jallib?hl=en
-~----------~----~----~----~------~----~------~--~---
