nandoc

NanDoc

this is a hack. this is nanDoc.

Summary

hack of nanoc3 to generate a static site of your (command-line) ruby project from your README etc.

Description

Generate a static site to document your ruby project from your README and other markdown-formatted documentation. Inject code examples from your unit tests into the generated docs. Extremely fragile hacks and some cool additions to nanoc3.

(This entire site is generated from a README and other docs with all of the code examples coming from unit test "scrapes.")

Does this match you?

• Tired of all the other unit-test-driven static documentation-site-generators that fall short of the usual promises?

• Agile development has your documentation content going rapidly stale?

• Sick of typing what you want to write by hand?

• Repeatedly hearing yourself repeat to yourself "Don't Repeat Yourself?"

• Don't underkill your documentation when it's so easy to Überkill™ it! Don't be fooled by impostors!

IF you ansewered YES to zero or more of the above questions (of those that were questions and not imperative statements), then DON'T WAIT! Press that big giant silver spherical DWIM button floating in the sky!

High Concept

A semi-attractive RIA sopping with Web 1.0 gooey-goodness is just a view on your existing vanilla documentation that you've surely been writing all along.

Nanoc3 makes making web sites fun and easy. Markdown makes documenting your projects fun and easy. Now, NanDoc puts the two together to make making web sites that present your markdown-documented projects tons of fun and super easy.

The crackiest part about it is when you start writing unit tests that provide example code for your docs. I really need to document this, both to document it and to showcase it. It's really important for humanity. It's tantamount to learning how to sing with your fingers. Or putting a webcam in your shower, depending on how good you are at writing tests, or how good your shower looks.

Installation

If we are lucky something like this will work: from the command line: ~~~ ~ > gem install -n ~/bin nandoc ~~~

(that -n ~/bin thing is just a matter of preference)

To hack, try something like this: from the command line: ~~~ ~/tmp > git clone [e-mail]:hipe/nandoc.git ~/tmp > cd nandoc ~/tmp/nandoc > rake gem ~/tmp/nandoc > gem install -n ~/bin pkg/nandoc-0.0.0.gem ~~~

before actually trying to use it, if you get that far, please read this proviso.

Usage Summary

Start with a markdown-formatted README file:

(see: test.rb - "basic usage -- readme")

Then, next to this readme create a nanoc3 site/project with nanDoc®-powered™ nanoc©:

(see: test.rb - 'basic usage -- create site')

Finally, compile your site with the nanoc3 compile command:

(see: test.rb - 'basic usage -- create site' - 'compile site')

From the command line start the nanoc3 (adsf) server: from the command line: ~~~ ~/tmp/my-site >nandoc view ~/tmp/my-site > ~~~

If all the bells are polished and whistles tuned, you will have a site as handsome, usable as self-unawarely-understatedly brilliant as this one, but stunningly and proudly your own:

(point and aim your browsing device to http://localhost:3000/)

(see: test.rb - 'basic usage -- create site' - 'index page body')

 

This entire readme file/site showcases much of the currently exisiting site generation haxies available in the nanDoc hacks of nanoc3; and the example code and output you see above is generated from the unit tests in this project. ¹

Even the above example page is generated by a README in a unit test and injected into this page (which itself is generated from the README of this project.)

Customizing your site is a matter of getting to know nanoc3 and discovering all the fantastic undocumented features hiding in nanDoc. (My next steps are to use this fun new tool to actually document how to use it to generate )

NanDoc. Genius never looked so stupid®.

---

appologies to william morgan's [trollop](http://trollop.rubyforge.org/) site, product, and person for unwittingly encouraging me, and providing the CSS styles for the highlighted ruby code.

Footnotes

1. checkout the treebis code to see some 'specdoc' features not used here. ↩