killercupgrock
Grock converts your nicely commented code into a gorgeous documentation where comments and code live happily next to each other.
To see how it works, just have a look at the documentation rendered from this repository.
Install
Install globally using npm install --global grock and invoke anywhere using grock --glob 'your/*.files'.
Or use it as a (dev-)dependency in your project and use the package.json script section to run it, e.g. with "scripts": {"docs": "grock"} and using npm run docs (read more about this here).
Usage
Basically:
$ grock --glob 'lib/**/*.js' --out 'docs' --verboseFor more information about available options, see bin/grock or run grock --help:
$ grock --help
Usage: grock [options]
You can also use a configuration file named .groc.json to specify these options.
The defaults below show the values of the .groc.json file when possible.
Options:
--help Show this message
--version Show grock version
--glob Set glob to match source files [default: ["*.md","bin/*","lib/**/*.coffee","lib/**/*.js","styles/**/*.coffee","styles/**/*.md","bin/*.js"]]
--out Render documentation into here [default: "docs/"]
--style Set the output style/theme [default: "solarized"]
--verbose Show more log output [default: false]
--index File to be used as root index [default: "Readme.md"]
--indexes Files to be used as indexes in sub directories [default: "Readme.md"]
--root The project's root directory [default: "."]
--whitespace-after-token Require whitespace after a comment token for a line to be considered a comment [default: true]
--repository-url URL to link to source files [default: "https://github.com/killercup/grock"]
--ext-scripts An array of external scripts for appending to the template [default: []]
--ext-styles An array of external styles for appending to the template [default: []]
--github Push generated docs to gh-pages branch [default: false]
--git-remote Overwrite the remote for --githubFor a list of supported languages, see the lib/languages.coffee file.
Config File
You can specify all the command line options in a .groc.json file (that is compatible to groc). This will automatically be loaded. This way you just need to save that file in your project directory and can use grock without arguments from now on.
Auto Publish Documentation to Github Pages
Using the --github flag, grock will try to write the documentation not to an output directory, but to the gh-pages branch of your git repository. If it succeeds, it will immediately push the new changes to the origin remote (can be specified by --git-remote.
Assuming you have specified all other options in ./.groc.json, you can then run:
$ grock --githubInspiration
- Literate programming (the programming methodology coined by Donald Knuth)
- Jeremy Ashkenas' docco
- The groc project -- this implementation is heavily based on this, but uses node.js streams
- Gulp.js, a build system that uses streams to transform files
What makes grock different?
In contrast to other node-based documentation generators like docco, groc, and docker, grock has the following advantages:
- It doesn't need pygments.
- Therefore it doesn't need python.
- Therefore it's faster than those other tools that need pygments.
- It renders a file tree and also a headline tree for each document.
- The default style (based on solarized) is responsive and looks actually quite good on a phone.
- It doesn't crash on malformed doc tags.
- It's based on streams. I've heard all the cool kids are using streams now.
Based on
- vinyl-fs for abstracting files
- Solarized
- marked
- highlight.js
Oh, and all the heavy lifting (splitting code and comments, parsing doc tags) is actually code from groc!
Roadmap
- [x] Be awesome with streams
- [x] Split code and comments
- [x] Highlight code
- [x] Generate TOC as JSON file
- [x] Render doc tags (like jsdoc)
- [x] CLI docs,
.groc.jsonconfig support - [ ] Correctly parse relative roots
- [x] Tests. Test for almost everything.
- [x] Add another style.
- [ ] Find a streaming code highlighter with hooks for comment segments
- [x] Parse files without extension
Contributing
Just fork the repo, implement some awesome feature or fix a bug and send a pull request.
Code Style and Guideline
- Document your code.
- Write code in CoffeeScript when possible and make sure
coffeelintdoesn't throw any warning or errors. - Make use of streams and promises. Those are good techniques.
- Split the code into as many independent, loosely coupled modules as possible and try to reuse existing ones.
- Write tests for those small modules.
- On the other hand, try to minimize (NPM) dependencies. Since this is a CLI tool, the startup time gets worse with every
require. - Run
npm testbefore committing. (Currently, this runscoffeelintandmocha).
Contributing to Styles
When adding a new style or editing an existing one, make sure you follow the guidelines in styles/Readme.md (e.g. adding an index file exporting copy, compile and template functions).
Changelog
See list of releases on Github or read the Changelog.md file.
License
MIT (see LICENSE).
