Documentation
John Freeman
appreciate comments too.
I have reached a stopping point for library development. Now, I am
switching to work on documentation.
I have a one primary desire for documentation: it should be generated
from the code and comments. The advantages are mainly for locality and
maintenance: I can see the documentation next to the code, and I do not
have to write the API in both JavaScript and some other markup.
There do not seem to be many options for JavaScript. It is a difficult
language for documentation generators because its flexibility provides a
number of ways to declare the same constructs. JSDoc seems like the
favorite:
JSDoc 2: http://code.google.com/p/jsdoc-toolkit/
JSDoc 3: https://github.com/micmath/jsdoc
JSDoc has issues, though. The latest version is poorly documented, and
the previous version is not much better. Changing the style of the
generated pages seems difficult.
Another option I discovered is called dox:
https://github.com/visionmedia/dox
Dox supports JSDoc tags and will return an AST. The AST is suitable for
further processing and template substitution using a tool like Mustache
or Handlebars.
I think I will start by fixing the documentation, using JSDoc tags, to
reflect the current state of development. I will use JSDoc to generate
ugly pages that will be uploaded to hotdrinkjs.com.
After I'm finished, I will try to use dox, some additional processing,
and Mustache to generate HTML sections for whatever template system we
are using for the tutorials. This way we can have a uniform and
attractive style for the whole site.
Thoughts? Ideas on alternative documentation generators? I do not think
a language-agnostic solution will be good because it won't be able to
infer anything from the code, but given how little can be inferred from
JavaScript, I could be wrong.
I looked at Docco, and do not like what it generates. I want something
with far more structure and cross-referencing.
- John
Jaakko Järvi
the library API reference etc.?
Tutorial, programmer's guide, and such artifacts I'd still think orgmode would do well.
I will post an example orgmode doc soon(ish).
Jaakko
John Freeman
> John, I'm assuming you mean all this for documentation of the library? Internal code documentation and
> the library API reference etc.?
Yes. After I wrote that email, I started work on a documentation
generator (to document private and public APIs). I have progressed
quickly thanks to the availability of a few decent open-source
libraries. I will get it in a usable state this week. It is published,
while still a work-in-progress, at GitHub:
https://github.com/thejohnfreeman/jfdoc
As for the tutorials (what I will call "client" documentation vs
"contributor" documentation), I have designed a tool-chain that should
let us use org-mode (or whatever markup we want) to generate them while
still producing a uniform style for the whole site. I will translate my
hand-drawn tool-chain flowchart into an image I can share with the group.
- John
John Freeman
> I will translate my
> hand-drawn tool-chain flowchart into an image I can share with the group.
You can see and edit the chart at Dabbleboard:
http://www.dabbleboard.com/draw?b=Guest1044352&i=3&c=af0591d328df63a567bf542bde7beb579f479bfe
In case it is vandalized, I uploaded an image of what I drew:
Question marks indicate where no preference has been given yet for the
tool or language for that step or data, respectively.
We will have at least three main components of the site that depend on
the code: API documentation, tutorials, and examples. Starting from the
bottom, we need to pick a tool for generating the site's pages from
templates and the intermediate formats for each component. If we go with
Liquid, the site could be hosted by GitHub (may or may not be
desirable). I have only the mildest preference for Dust simply because
I'm already using it.
For the API documentation, I want to use the tool I'm writing (jfdoc for
lack of a better name) to generate HTML from Dust templates instantiated
with data I lift from the code and comments.
For the tutorials, we have decided to use Org-mode which will allow us
to generate HTML that pulls directly from the example code (no editing
required).
For the examples, I envision a page like our last demo where you could
choose to load one of a number of available examples and play with it
directly in the browser. Knockout has a really fancy subdomain
(http://learn.knockoutjs.com/) that does similar. Whatever tool we use
should pull directly from the example code, just like Org-mode.
As for the intermediate formats, I think we will end up with HTML,
though another option could be possible - whatever the last tool in the
chain wants.
- John
Gabriel Foust
templating library called Heist. It's actually part of the Snap web
framework, but it can be used on its own just to generate static HTML
files. The advantage to a template library is that it supports some
of the operations John was discussing earlier: e.g. making a single
template that all other templates inherit from, specializing as
necessary. Also, since it's just a stand-alone program it's a little
easier to do things like access content from a bunch of files on the
hard drive.
So basically I wrote a Haskell program that takes the different
fragments of an example (the HTML source, the JS source, and the
description) and combines them into a single HTML file. It generates
the HTML for just a single example (passed as a command line
argument), but I made a Makefile that lists all the examples and uses
the Haskell program to build them. So running "make" will first build
the Haskell program, then use the Haskell program to generate all the
HTML files.
If anyone wants to see it, I put a tar file in my home directory on
Sun:
sun.cs.tamu.edu:/home/grads/g/gfoust/hotdoc.tar.gz
(It's not in Git since chances are we'll never use it.)
On Mar 13, 10:37 am, John Freeman <jfreema...@gmail.com> wrote:
> On 3/12/2012 6:40 PM, John Freeman wrote:
>
> > I will translate my
> > hand-drawn tool-chain flowchart into an image I can share with the group.
>
> You can see and edit the chart at Dabbleboard:
>