1 | # groc
|
2 |
|
3 | Groc takes your _documented_ code, and generates documentation that follows the spirit of literate
|
4 | programming. Take a look at the [self-generated documentation](http://nevir.github.com/groc/),
|
5 | and see if it appeals to you!
|
6 |
|
7 | It is very heavily influenced by [Jeremy Ashkenas](https://github.com/jashkenas)'
|
8 | [docco](http://jashkenas.github.com/docco/), and is an attempt to further enhance the idea (thus,
|
9 | groc can't tout the same quick 'n dirty principles of docco).
|
10 |
|
11 |
|
12 | ## What does it give you?
|
13 |
|
14 | Groc will:
|
15 |
|
16 | * Generate documentation from your source code, by displaying your
|
17 | [Markdown](http://daringfireball.net/projects/markdown/) formatted comments next to the code
|
18 | fragments that they document.
|
19 |
|
20 | * Submit your project's documentation to the [github pages](http://pages.github.com/) for your
|
21 | project.
|
22 |
|
23 | * Generate a searchable table of contents for all documented files and headers within your project.
|
24 |
|
25 | * Gracefully handle complex hierarchies of source code across multiple folders.
|
26 |
|
27 | * Read a configuration file so that you don't have to think when you want your documentation built;
|
28 | you just type `groc`.
|
29 |
|
30 |
|
31 | ## How?
|
32 |
|
33 | ### Installing groc
|
34 |
|
35 | Groc depends on [Node.js](http://nodejs.org/) and [Pygments](http://pygments.org/). Once you have
|
36 | those installed - and assuming that your node install came with [npm](http://npmjs.org/) - you can
|
37 | install groc via:
|
38 |
|
39 | npm install -g groc
|
40 |
|
41 | For those new to npm, `-g` indicates that you want groc installed as a global command for your
|
42 | environment. You may need to prefix the command with sudo, depending on how you installed node.
|
43 |
|
44 |
|
45 | ### Using groc (CLI)
|
46 |
|
47 | To generate documentation, just point groc to source files that you want docs for:
|
48 |
|
49 | groc *.rb
|
50 |
|
51 | Groc will also handle extended globbing syntax if you quote arguments:
|
52 |
|
53 | groc "lib/**/*.coffee" README.md
|
54 |
|
55 | By default, groc will drop the generated documentation in the `doc/` folder of your project, and it
|
56 | will treat `README.md` as the index. Take a look at your generated docs, and see if everything is
|
57 | in order!
|
58 |
|
59 | Once you are pleased with the output, you can push your docs to your github pages branch:
|
60 |
|
61 | groc --github "lib/**/*.coffee" README.md
|
62 |
|
63 | Groc will automagically create and push the `gh-pages` branch if it is missing.
|
64 |
|
65 | There are [additional options](http://nevir.github.com/groc/cli.html#cli-options) supported by
|
66 | groc, if you are interested.
|
67 |
|
68 |
|
69 | ### Configuring groc (.groc.json)
|
70 |
|
71 | Groc supports a simple JSON configuration format once you know the config values that appeal to you.
|
72 |
|
73 | Create a `.groc.json` file in your project root, where each key maps to an option you would pass to
|
74 | the `groc` command. File names and globs are defined as an array with the key `globs`. For
|
75 | example, groc's own configuration is:
|
76 |
|
77 | {
|
78 | "globs": ["lib/**/*.coffee", "README.md", "lib/styles/*/style.sass", "lib/styles/*/*.jade"],
|
79 | "github": true
|
80 | }
|
81 |
|
82 | From now on, if you call `groc` without any arguments, it will use your pre-defined configuration.
|
83 |
|
84 |
|
85 | ## Literate programming?
|
86 |
|
87 | [Literate programming](http://en.wikipedia.org/wiki/Literate_programming) is a programming
|
88 | methodology coined by [Donald Knuth](http://en.wikipedia.org/wiki/Donald_Knuth). The primary tenet
|
89 | is that you write a program so that the structure of both the code and documentation align with
|
90 | your mental model of its behaviors and processes.
|
91 |
|
92 | Groc aims to provide a happy medium where you can freely write your source files as structured
|
93 | documents, while not going out of your way to restructure the code to fit the documentation.
|
94 | Here are some suggested guidelines to follow when writing your code:
|
95 |
|
96 | * Try to keep the size of each source file down. It is helpful if each file fulfills a specific
|
97 | feature of your application or library.
|
98 |
|
99 | * Rather than commenting individual lines of code, write comments that explain the _behavior_ of a
|
100 | given method or code block. Take advantage of the fact that comments can span that method.
|
101 |
|
102 | * Make gratuitous use of lists when explaining processes; step by step explanations are extremely
|
103 | easy to follow!
|
104 |
|
105 | * Break each source file into sections via headers. Don't be afraid to split source into even
|
106 | smaller files if it makes them more readable.
|
107 |
|
108 | Writing documentation is _hard_; hopefully groc helps to streamline the process for you!
|
109 |
|
110 |
|
111 | ## What's in the works?
|
112 |
|
113 | Groc wants to:
|
114 |
|
115 | * [Fully support hand-held viewing of documentation](https://github.com/nevir/groc/issues/1). It
|
116 | can almost do this today, but the table of contents is horribly broken in the mobile view.
|