[Users] How to generate JS API docs with Sphinx and JST

[Just van den Broecke]

Hi Volker,

On 25-05-11 13:10, Volker Nathusius wrote:
> Hi,
>
> start of May I was also trying to manage a similar way of documenting code based on GeoExt,
> and my conclusion was that the GeoExt setup of paver+sphinx+jstools is rather unique.
True, but strictly Paver is not required. I have just managed to setup a 
documentation chain on Ubuntu and Mac with just Sphinx+JSTools using 
easy_setup to install and without virtualenv. Paver is used for some 
preprocessing that can be done with standard commandline tools or Ant (I 
use Ant similar to 
https://github.com/opengeo/gxp/blob/master/build/build.xml).

The trick is to have the proper JST template (.jst file)  setup in 
combination with proper commenting in the JS files. In the first phase 
via "jst" the JS files are converted to restructured text (.rst) and 
Sphinx will do the .rst to .html (or whatever) conversion. For the API 
docs this is quite straightforward. The way the "examples" 
(examples.html) are processed and rendered is more involved and more of 
a smart hack with jst/sphinx/ExtJS/JQuery but also not required for API 
docs.
>
> As far as I could grasp, a virtual python environment is necessary, then the
> extraction of JS documentation is managed by paver, which delegates to jstools.
Not neccessarily, see above.
>
> Based on that, I found a workflow that produces API docs, but I would be glad to learn
> about a different and more comfortable way, preferably without paver.
> I found no manual to jst however...
After some cleanup our toolchain will be online as free source somewhere 
this week.

best,

Just

>
> Regards, Volker
>
>
>
>
>>>/  Hi,
> />>/
> />>/  I am trying to use a similar way to generate API docs within our GeoExt
> />>/  extended components, i.e. using Sphinx with JST templates, but somehow
> />>/  from the GeoExt repository athttp://trac.geoext.org/browser  I can't
> />>/  find out how this is done. Sphinx itself is no problem but somehow I
> />>/  need a "JST" tool that generates .rst files from JS files first ? Also
> />>/  looked into the GXP repository
> />>/  (https://github.com/opengeo/gxp/blob/master/build/build.xml) but to no
> />>/  avail (executable "jst"?).
> />>/
> />>/  Thanks for any help, best,
> />>/
> />>/  --Just
> />>/
> />>/  Just van den Broecke
> />>/  The Netherlands
> />>/  www.justobjects.nl  <http://www.justobjects.nl>/
>
>
>
>
> --
>
>    Volker von Nathusius
>
>    terrestris GmbH&  Co. KG
>    Irmintrudisstraße 17
>    53111 Bonn
>
>    Tel:    ++49 (0)228 / 96 28 99 -53
>    Fax:    ++49 (0)228 / 96 28 99 -57
>
>    Email:nathusius at terrestris.de
>    Web:http://www.terrestris.de
>
>    Amtsgericht Bonn, HRA 6835
>    Komplementärin:  terrestris Verwaltungsgesellschaft mbH
>    vertreten durch: Hinrich Paulsen, Till Adams
>
>
>
> _______________________________________________
> Users mailing list
> Users at geoext.org
> http://www.geoext.org/cgi-bin/mailman/listinfo/users


-- 
kind regards / met vriendelijke groet,

--Just

Just van den Broecke  just at justobjects.nl
Just Objects B.V.     tel +31 65 4268627 Skype: justb4
The Netherlands       http://www.justobjects.nl