Write your code/docs once, don't repeat yourself. Changes/updates to docs are guaranteed to match your project
I wrote a Rails course, that required I build an app and write documentation for building said app. Wouldn't it be cool if instead while I write the documentation I could automate the building of my app?
Totally! That's this, this is that thing.
Write docs that build software.
Why docs to code and not code to docs? Code is hard, cold and machine runnable. Docs are soft, consumed by people, and need high flexability. It's easier to explicitly tell the machine what code you want generated, then to go the other way.
For now this software is distributed as a rubygem. Install it manually:
$ gem install docdown
or add it to your Gemfile:
Run the docdown command on any makdown file
$ docdown build my_file.md
This will generate a project folder with your project in it, and a markdown README.md with the parsed output of the markdown docs.
Docdown uses github flavored markdown and the html-pipeline behind the scenes. This means you write like normal but in your code sections you can add special annotations that when run through docdown can generate a project.
All docdown commands are prefixed with three colons
::: and are inclosed in a code block a
command such as
$ which is an alias for
bash commands like this:
``` ::: $ git init . ```
Nothing before the three colons matters. The space between the colons and the command is optional.
If you don't want the command to output to your markdown document you
can add a minus symbol
- to the end to prevent it from being
``` :::- $ git init . ```
If you want the output of the actual command to be rendered to the screen you can use an equal sign so that
``` :::= $ ls ```
Might generate an output something like this to your markdown doc:
``` $ ls Gemfile README.rdoc app config.ru doc log script tmp Gemfile.lock Rakefile config db lib public test vendor ```
That's how you manipulate the shell with docdown, let's take a look at manipulating code.
Right now you can only write to files. Use the
write keyword followed by a filename, on the next line(s) put the contents of the file
``` ::: write config/routes.rb Example::Application.routes.draw do root :to => "pages#index" namespace :users do resources :after_signup end end ```
If you wanted to change
products you would write to the same file again.
``` ::: write config/routes.rb Example::Application.routes.draw do root :to => "pages#index" namespace :products do resources :after_signup end end ```
To delete files use bash
- Debug output
- Fail and exit on non zero exit code
- Bash commands with side effects (cd; pwd; on different lines should actually change working directory)
- Better line matching for backtrace