This is your weblog on Dexy!

Well, this last weekend, instead of writing code or blog posts, I fiddled with Dexy. And I’ve come to one simple conclusion:

Dexy is freakin’ awesome!

Dexy is a documentation writer’s dream tool: it takes words about code, pictures, and original unchanged source code and generates absolutely gorgeous documentation. In fact, Dexy generated the markup for this entire post from just a few small files and automatically posted it to my WordPress blog. Now that is utility!

Here is a Factor script:

! Copyright © 2011 Your name.

! See http://factorcode.org/license.txt for BSD license.

USING: http.client json.reader kernel prettyprint strings multiline ;

IN: weblog.dexyfied

#! @export section-1

: test1. ( — )

    "http://oohembed.com/oohembed/?url=http%3A//www.flickr.com/photos/fuffer2005/2435339994/"

    http-get nip >string json> . ;

See that funky @export comment in there? That lets Dexy pull out just a small section of that script:

: test1. ( — )

    "http://oohembed.com/oohembed/?url=http%3A//www.flickr.com/photos/fuffer2005/2435339994/"

    http-get nip >string json> . ;

I even got simple interactive Factor sessions going:

( scratchpad ) USE: weblog.dexyfied

( scratchpad ) test1.

H{

    { "version" "1.0" }

    { "provider_name" "Flickr" }

    { "width" "300" }

    { "height" "300" }

    { "author_name" "fuffer" }

    { "title" "echo 2" }

    { "cache_age" 3600 }

    { "type" "photo" }

    {

        "url"

        "http://farm4.static.flickr.com/3092/2435339994_4ab42c3c20.jpg"

    }

    { "provider_url" "http://www.flickr.com/" }

    { "author_url" "http://www.flickr.com/photos/fuffer2005/" }

}

( scratchpad ) 

That’s the result of running this Factor program:

USE: weblog.dexyfied

test1.

It’s re-generated each time that the file changes: no bitrot, just exactly what happens when you type that code into the Factor listener, always in sync with the code on disk. This is sort of like Literate Programming but without doing weird things to the source code while retaining the ability to structure the documentation like, well, a document.

Still a bunch of bugs with the interactive handler, and the splitting of Factor “sections” is a hack, but I hope to improve these things as I go. Already, this beats the old “copy-and-paste” approach by a factor of approximately 10 jillion. Take a look at the source to this post.