Repository navigation
How to generate the documentation? #69
Description
@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!
Activity
mildsunrise commentedon Sep 6, 2013
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 commentedon Sep 9, 2013
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 commentedon Sep 9, 2013
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:
docfolder and markdown files in there (each of the files represent a section of the API).See the
docfolder in Node.directories.docentry pointing to that folder inmy
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 commentedon Sep 9, 2013
@ 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.