Refresh Austin - Intro to Dexy

Refreshing Documentation
An Introduction to Dexy

Ana Nelson

dexy.it

July 12, 2011

Dexy for Web Apps

• Install Guide

Dexy for Web Apps

• Install Guide
• User Guide

Dexy for Web Apps

• Install Guide
• User Guide
• Developer Docs

The Big Idea

No Dead Code
• Any code you show comes from a live, runnable ﬁle.
• Any images or output you show comes from running live code.

Beneﬁts

• Correctness
• Maintainability
• Workﬂow

Tool for the job

Dexy
• Open Source (mostly MIT, some AGPL)
• Written in Python
• Command Line, Text Based
• * Agnostic
• My Day Job and my Mission in Life

Demo

What we want to create:
• Install Guide
• User Guide
• Developer Docs
What we need:
• An App!
• Install Script
• Watir Script

An App

web.py todo list app http://webpy.org/src/todo-list/0.3

DB Schema

CREATE TABLE todo (
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT
);

model.py

import web

db = web.database(dbn= ’ sqlite ’ , db= ’ todo.sqlite3 ’ )

def get_todos():
return db.select( ’ todo ’ , order= ’ id ’ )

def new_todo(text):
db.insert( ’ todo ’ , title=text)

def del_todo(id):
db.delete( ’ todo ’ , where= " id=$id " , vars=locals())

base.html

$def with (page)

<html>
<head>
<title>Todo list</title>
</head>
<body>

$:page

</body>
</html>

index.html
$def with (todos, form)

<table>
<tr>
<th>What to do ?</th>
<th></th>
</tr>
$for todo in todos:
<tr>
<td>$todo.title</td>
<td>
<form action= "/del/$todo.id" method= "post" >
<input type= "submit" value= "Delete" />
</form>
</td>
</tr>
</table>

<form action= "" method= "post" >
$:form.render()
</form>

todo.py

""" Basic todo list using webpy 0.3 """
import web
import model

urls = (
’ / ’ , ’ Index ’ ,
’ /del/( d+) ’ , ’ Delete ’
)

render = web.template.render( ’ templates ’ , base= ’ base ’ )

todo.py

class Index:

form = web.form.Form(
web.form.Textbox( ’ title ’ , web.form.notnull,
description= " I need to: " , size=75),
web.form.Button( ’ Add todo ’ ),
)

todo.py

def GET(self):
""" Show page """
todos = model.get_todos()
form = self.form()
return render.index(todos, form)

todo.py

def POST(self):
""" Add new entry """
form = self.form()
if not form.validates():
todos = model.get_todos()
return render.index(todos, form)
model.new_todo(form.d.title)
raise web.seeother( ’ / ’ )

todo.py

class Delete:

def POST(self, id):
""" Delete based on ID """
id = int(id)
model.del_todo(id)
raise web.seeother( ’ / ’ )

todo.py

app = web.application(urls, globals())

if __name__ == ’ __main__ ’ :
app.run()

install script

Install Script

install script

apt-get update
apt-get upgrade -y --force-yes

apt-get install -y python-webpy
apt-get install -y mercurial
apt-get install -y sqlite3

install script

hg clone https://bitbucket.org/ananelson/dexy-examples
cd dexy-examples
cd webpy

sqlite3 todo.sqlite3 < schema.sql

python todo.py

install script

export UBUNTU_AMI= "ami-06ad526f" # natty
cd ~/.ec2
ec2run $UBUNTU_AMI -k $EC2_KEYPAIR
-t t1.micro -f ~/dev/dexy-examples/webpy/ubuntu-install.sh
(Make sure to allow access to port 8080 in security group.)

Now What

• We have an app and we have it running.
• We have an install script which we can use to create an install guide.
• Now we need a script to show how the app works.

Watir

• Watir lets us automate the web browser
• Can be integrated with functional tests
• For extra awesomeness, let’s use Watir to take screenshots

watir

require ’rubygems’
require ’safariwatir’

IP_ADDRESS = ENV[ ’EC2_INSTANCE_IP’ ]
PORT = ’8080’
BASE = " http:// #{ IP_ADDRESS } : #{ PORT } / "

watir

We create a reference to the browser:
browser = Watir::Safari.new
And deﬁne a helper method to take screenshots:
def take_screenshot(filename)
sleep(1) # Make sure page is finished loading.
‘ screencapture #{ filename } ‘
‘ convert -crop 800x500+0+0 #{ filename } #{ filename } ‘
end

watir

Now we’re ready to go!
browser.goto(BASE)
take_screenshot( " dexy--index.png " )

watir

Let’s enter a TODO:
browser.text_field( :name , " title " ).set( " Prepare Refresh Austin Talk Demo
take_screenshot( " dexy--enter.png " )

watir
Click the ”Add todo” button to add it. We’ll verify that it was actually added.
browser.button( :name , " Add todo " ).click
raise unless browser.html.include?( " <td>Prepare Refresh Austin Talk Demo</td>
take_screenshot( " dexy--add.png " )

watir

And delete it again:
browser.form( :index , 1).submit
take_screenshot( " dexy--delete.png " )

• Now we have screenshots we can use in our documentation, and which
we can update any time.
• We also know that the steps described in our screenshots WORK.
• Note that we are also validating our install script.
• You will want to return your DB to its original state within your script, or
have a reset method in your app.

Refresh Austin - Intro to Dexy

More Related Content

What's hot

Viewers also liked

Similar to Refresh Austin - Intro to Dexy

Recently uploaded

Refresh Austin - Intro to Dexy