The challenge with documenting code is getting your code or your results into your document. With most tools, you need to copy and paste, or type your code directly in to your document. This is cumbersome and difficult, as anyone who has tried to type Python into a WordPress blog post can tell you. It also means that you have no way to test your code once it is in your document. It is dead code, and the only way to find typos or errors is with very careful proofreading (usually done by your customers).

Dexy takes a different approach. With Dexy you type your code into normal code files, Python in .py files, Java in .java files. Then you bring your code into your document, running it through various filters to get the effect you want. You can modify your code at any time and rebuild your document, and all the references will be updated.

Filters give you amazing flexibility. For example, you can show off raw code:

a = 6
b = 7
c = a*b
print "the answer is", c

Or you can show off code with syntax highlighting

a = 6
b = 7
c = a*b
print "the answer is", c

You can run the code through an interpreter, showing input and output (great for writing tutorials):

Python 2.7.2+ (default, Oct  4 2011, 20:06:09) 
[GCC 4.6.1] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> a = 6
>>> b = 7
>>> c = a*b
>>> print "the answer is", c
the answer is 42

You can just show off the output:

the answer is 42

Or you can work the results directly in to your document. Say, did you know that when you multiply 6 by 7, you get 42? (View the source of this page to see how that sentence was put together.)

This approach means that the code you document is the actual code you use, and it can be run independently, tested, tweaked and updated at any time. You can publish documents with confidence that your examples and results are free from typos and can be easily audited and verified.

Here is a very small sample of languages and modes supported by Dexy (check out the filter documentation for a complete list):

print("Hello, R world!")

#include <stdio.h>

main()
{
    printf("Hello, C world!");
}

public class hello {
  public static void main(String args[]) {
    System.out.println("Java Hello World!");
  }
}

print("Hello, R world!")

#include <stdio.h>

main()
{
    printf("Hello, C world!");
}

public class hello {
  public static void main(String args[]) {
    System.out.println("Java Hello World!");
  }
}

> print("Hello, R world!")
[1] "Hello, R world!"

[1] "Hello, R world!"

Hello, C world!

Java Hello World!

You can view the source for this page to see the different filters used in that table.

With Dexy, you can present your code in whatever way makes the most sense for your document. And, if you want to use a different interpreter or compiler, or add support for a new language, it's as simple as writing a new filter. Check out the python output, python console, R, C and Java filters to see how it's done.

Dexy is an authoring tool that just happens to include great utilities for incorporating code and results into your writing. Dexy lets you create documentation projects with any number of documents, of any type, in any configuration. Dexy is great at building websites, so you can even write a HTML presentation layer around your other documents, and build everything all at once.

While Dexy gives you total free-form capabilities, it also helps you automate repetitive content, but with much more control than automated tools like javadoc. Use filters like the split filter, or write custom scripts or filters to parse your repetitive content, then iterate over these structures in your documents, pulling out the content you want in any format.

You can just start writing content in any format. You can use templates to insert dynamic content anywhere in your document. Dexy will help you compile formats like Markdown, Textile, Asciidoc and LaTeX, and of course it's easy to add support for new formats or utilities. Dexy filters can also do things like wordcount, spellcheck and text analysis, and you can use Dexy to consistently prepare your documents to a publisher's specifications.

Templates let us insert dynamic content into our documents. This can be a chunk of text, a number, or a dynamically generated path to an image file. Templates in Dexy are just filters, and as your document passes through the filter any template tags you have are filled in with content.

Templates are what give your documents real power and flexibility. The Jinja2 template filter is the recommended one to get started with, although Mako and other templating systems are also available, and the new Template Plugin system in Dexy 0.5.0 makes it trivial to add new templating systems and to share preprocessing code across multiple templating systems.

Dexy is flexible enough not just to generate your documents with their dynamic content, but to do a lot more project automation and integration besides. Dexy's filters are able to run any Python code you want, so that means they can do things like interact with remote APIs, construct .tgz archives of generated files, or pretty much anything else you can think of. You aren't even limited to Python, Dexy filters can wrap an executable or run code written in another language, so you can do just about anything.

An obvious integration is to publish HTML content to a blog, and Dexy has integration with WordPress, Posterous and Tumblr (and it's straightforward to add more). You can also interact with APIs to import data for analysis.

To get started using Dexy, you can install it and then work through the tutorials which will introduce some basic concepts and give you some experience with the most common and useful filters. The user guide is still in development but the chapter on Documents, Dependencies and Filters goes through the basics of Dexy in detail. When you have finished the tutorials, then the project templates are a great way to explore more or easily start a new project. The example gallery has more advanced examples which can give you an idea of different ways to use dexy. Finally the filter references show you all the standard Dexy filters and have examples for many of them. Remember that this whole website was generated using Dexy, so if you see something interesting you can always look at the page's source code to see how it was done. Happy documenting!