docket

minimalist documentation generator

github

docket is a tool I created for myself which lets one easily extract github-flavored-markdown from source code. It isn't particularly smart and it doesn't try to do too much, but it's easy to use. The simple idea is that you should put your documentation in the same place as your code.

The implementation is inspired and uses some code by docco.

Sections

To make a section of comments visible to docket, use a named header bracketed with tildes(~). for example,

  //~demosection~
  // Blah!

would begin a section called demosection in javascript. The section will continue until there is a line that is not a comment (i.e., either code or whitespace). In this case, the demosection would contain the text " Blah". The tilde can be changed to any other symbol or pair of symbols via the -b command line option.

Re-opening sections

Sections can be re-opened at any time, that is if you, at a later point in the file, added the line

  //~demosection~
  // More blah!

Any comments after that line would be put in the same section as the first comment.
demosection would now contain " Blah!\n More blah!"

Output sections

Any sections whose name ends in .out will be output into docket's base directory, that is the current directory or the directory specified with the -d command line option. By default the output will be in html generated by interpretting the section text as markdown, but with the -m option you can output the raw markdown. We use the same github-flavored-markdown as docco.

Verbatim sections

sections whose name begins with verbatim: are special in that the rest of the file, code and all, are added to the section.

Ordered sections

Across several files, there are no guarentees about the order files are added to sections. To ensure a particular ordering, use square brackets [] at the end of the section name. e.g:

  //~ordered[a]~
  // this happens first


  //~ordered[b]~
  // this happens second

The tokens inside the square brackets are sorted in lexicographic order.

References

While a section is open, any tilded identifiers become references to other sections. after all the input files are parsed, the references are filled in with the text of the referenced section. For example,

  //~containersection~
  //~subsection~

  //.. stuff goes here
  //~subsection~
  //info!

Would cause ~containersection~ to contain "info!". If the referenced section is never defined, no replacement is made. References can be nested arbitrarily but behavior is undefined if there is a reference loop (i.e. a section references itself).

docket is released under a permissive license, but it uses some code and ideas from docco, which is under the MIT license.