Docdown
What
Write your code/docs once, don't repeat yourself. Changes/updates to docs are guaranteed to match your project
Why
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.
Install
For now this software is distributed as a rubygem. Install it manually:
$ gem install docdown
or add it to your Gemfile:
gem 'docdown`
Use It
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.
Write it
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
rendered.
```
:::- $ 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.
Files
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 users
to 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 $
command.
TODO
- Debug output
- Fail and exit on non zero exit code
- Breakpoints?
- Bash commands with side effects (cd; pwd; on different lines should actually change working directory)
- Better line matching for backtrace