How to generate the documentation?

[iamwilhelm]

@samcday How were you planning on generating the documentation? I'd like to be able to get on that, so we can have non-broken docs while we talk about the maintainer transition. Thanks!

[mildsunrise]

Well, the maintainer transition turned out to be a bigger thing
(discussing wether we'll deprecate gitteh in favor of nodegit,
or we'll continue development)

[lushzero]

I've played with a couple of different tools and am currently using groc. Is there a best practice tool for node project specifically, I see a mix of not great doc most of the time.

[mildsunrise]

groc? Didn't know of that tool. It's like a more featured Docco..?

To document my API I follow the method used in
Node and recommended by NPM:

• I create a doc folder and markdown files in there (each of the files represent a section of the API).
  See the doc folder in Node.
• I put the directories.doc entry pointing to that folder in
  my package.json.

The markdown files follow have special "commands" like
specifying parameters for a function, etc.

And if I ever want to generate good-looking HTML pages from
the markdown files, I use the same tool that generates Node's.

[lushzero]

@ jmendeth groc is a code "autodoc" tool that has integration with github pages and produces in my opinion a very nicely formatted HTML output by default. It's not perfect and I think it was built primarily for "literate programming" which I don't necessarily take that seriously but it was the easiest/fastest/fewest dependencies/prettiest of several tools I tried including Docco.

I wasn't aware of that handy little joyent tool somehow so thanks for that. That's perhaps a nice complement to something fuller featured more verbose type generating tool like groc/etc.