Loading…

Flash Player 9 (or above) is needed to view presentations.
We have detected that you do not have it on your computer. To install it, go here.

Like this presentation? Why not share!

Dexy on rails

on

  • 1,609 views

Talk for Conferencia Rails (Madrid, November 2010) about using Dexy for automated web app documentation.

Talk for Conferencia Rails (Madrid, November 2010) about using Dexy for automated web app documentation.

Statistics

Views

Total Views
1,609
Views on SlideShare
1,608
Embed Views
1

Actions

Likes
2
Downloads
16
Comments
0

1 Embed 1

http://blog.dexy.it 1

Accessibility

Categories

Upload Details

Uploaded via as Apple Keynote

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />

Dexy on rails Dexy on rails Presentation Transcript

  • Dexy on Rails Documentation for the Whole Stack 4 November 2010 - Conferencia Rails
  • Contact Information http://dexy.it http://ananelson.com @dexyit @ananelson ana@ananelson.com
  • http://bitbucket.org/ananelson/dexy-rails Download links if you don’t have Mercurial.
  • This Talk ✤ What is Dexy? ✤ Dexy Philosophy ✤ Dexy for Rails
  • What is Dexy? ✤ Tool for document automation. ✤ Smart enough for the most complex documents. ✤ Simple and flexible enough to use every day. ✤ Written in Python, Usable for Any* Language
  • How is Dexy different? ✤ Write whatever you want, in any format. ✤ Mix any match: ✤ code snippets in any number of languages ✤ code transcripts ✤ code output ✤ artifacts (like graphs, audio, video)
  • Filters ✤ doc.textile|textile ✤ doc.html|jinja ✤ doc.tex|jinja|latex ✤ doc.textile|jinja|textile|cssinline
  • Inputs code.rb|pyg index.html|jinja code.rb|rb
  • How does Dexy work? ✤ Filters ✤ Dependencies, Topological Sort ✤ Smart Caching ✤ Templating ✤ Sectioning
  • Status of Dexy ✤ Very solid core. ✤ Usable now if you have strong need/interest. ✤ Wait about 3 months for stable API. ✤ For now, need *some* Python (but not much and lots of examples to follow).
  • Philosophy ✤ 1. Work with the tools you like. ✤ Document any language or tool. ✤ Use any documentation tool you like (will be made better by Dexy). ✤ 2. Use the right tool for the job. ✤ rdoc does 1 thing well ✤ just use it for what it does well, not everything!
  • Philosophy ✤ 3. Documentation is a Product ✤ The Audience, not the Tool, should determine what you write. ✤ 4. Iterate your Documentation ✤ By making it easy to reproduce/iterate your documentation, Dexy helps you incorporate feedback continuously.
  • Philosophy ✤ 5. Talk is Cheap ✤ Write as much as you want. Dexy makes it fast and easy to write all sorts of documents. Practice your writing, and be copious! ✤ 6. Don’t Pollute Your Code ✤ Code comments are code comments. Code comments are NOT developer documentation.
  • Philosophy ✤ 7. No Dead Code ✤ If it’s not live, runnable code, then it’s decomposing. ✤ 8. Start with a Blank Virtual Machine
  • Dexy on Rails
  • Dexy on Rails ✤ Sysadmin Documentation ✤ Developer Documentation ✤ End-User Documentation ✤ (representative, not exhaustive)
  • Sysadmin Documentation ✤ PDF Install Guide ✤ PDF - so can be printed out if necessary during install ✤ Based on actual install script. ✤ Run on blank VM so we can’t miss any steps.* ✤ Chop script into sections, explain in the document. ✤ Enough comments in the code so it’s understandable by itself, no more.
  • # This install script was developed to be run on the TurnKey Linux Lucid Core # image. http://www.turnkeylinux.org/core ### @export "utils" apt-get update apt-get install -y build-essential apt-get install -y libcurl4-openssl-dev ### @export "ruby" apt-get install -y ruby ruby1.8-dev apt-get install -y rubygems apt-get install -y libopenssl-ruby ### @export "db" apt-get install -y libdbd-sqlite3-ruby ### @export "rails" gem install rails --version=2.3.8 --no-rdoc --no-ri ### @export "passenger" gem install passenger --no-rdoc --no-ri ### @export "gem-bin" export PATH=/var/lib/gems/1.8/bin:$PATH ### @export "vcs" apt-get install -y mercurial ### @export "install-app" cd /srv/
  • section{Install Guide} These installation instructions are for a TurnKey Linux Lucid Code image. Please adjust as necessary for different packaging systems. First, we make sure that package information is up to date, then we install some useful utilities. << d['sections']['install-turnkey-lucid.sh|idio|l']['utils'] >> Next we install Ruby. << d['sections']['install-turnkey-lucid.sh|idio|l']['ruby'] >> We will be using the Sqlite3 database. << d['sections']['install-turnkey-lucid.sh|idio|l']['db'] >> We install rails itself << d['sections']['install-turnkey-lucid.sh|idio|l']['rails'] >>
  • Install Guide Ana Nelson November 4, 2010 This is an example of sysadmin documentation generated using Dexy. Install Guide These installation instructions are for a TurnKey Linux Lucid Code image. Please adjust as necessary for different packaging systems. First, we make sure that package information is up to date, then we install some useful utilities. apt-get update apt-get install -y build-essential apt-get install -y libcurl4-openssl-dev Next we install Ruby. apt-get install -y ruby ruby1.8-dev apt-get install -y rubygems apt-get install -y libopenssl-ruby We will be using the Sqlite3 database. apt-get install -y libdbd-sqlite3-ruby We install rails itself gem install rails --version=2.3.8 --no-rdoc --no-ri
  • Developer Documentation ✤ HTML - easy to browse, fast to update ✤ Cucumber Source ✤ Cucumber Output ✤ Controller and View Source Code ✤ Screenshots
  • Feature: Search In order to look up information I need to use the search option Scenario: Search for Abc # artifacts/b9352264c66edc4aa2d492f805d3ceb1.work.feature:5 Given that I am on the search page # artifacts/cc3349daf048ef5be9f190693fd87ec9.rb:7 When I search for Abc # artifacts/cc3349daf048ef5be9f190693fd87ec9.rb:15 Then I should see results for Abc # artifacts/cc3349daf048ef5be9f190693fd87ec9.rb:22 TODO (Cucumber::Pending) ./artifacts/cc3349daf048ef5be9f190693fd87ec9.rb:23:in `/^I should see results for Abc$/' artifacts/b9352264c66edc4aa2d492f805d3ceb1.work.feature:8:in `Then I should see results for Abc' 1 scenario (1 pending) 3 steps (1 pending, 2 passed) 0m5.421s
  • require 'spec' require 'safariwatir' BROWSER = Watir::Safari.new BASE = "http://172.16.251.137:3000" Given /^that I am on the search page$/ do BROWSER.goto("#{BASE}/search") BROWSER.html.include?("Please enter your search query:").should be_true sleep(1) system("/usr/sbin/screencapture {{ a.create_input_file('before-enter-search', 'png') }}") system("convert -crop 600x300+0+0 {{ a.create_input_file('before-enter-search', 'png') }} {{ a.create_input_file('before-enter-search', 'png') }}") end When /^I search for Abc$/ do BROWSER.text_field(:name, "query").set("Abc") sleep(1) system("/usr/sbin/screencapture {{ a.create_input_file('after-enter-search', 'png') }}") system("convert -crop 600x300+0+0 {{ a.create_input_file('after-enter-search', 'png') }} {{ a.create_input_file('after-enter-search', 'png') }}") end Then /^I should see results for Abc$/ do pending # express the regexp above with the code you wish you had end
  • class SearchController < ApplicationController end Please enter your search query: <form action="search"> <input name="query" /> <input type="submit" /> </form>
  • <h1>Search Feature</h1> Here is the Cucumber specification: <pre> {{ d['search.feature|dexy'] }} </pre> <h2>Test Implementation and Output</h2> Test implementation: {{ d['search.rb|pyg|inlinecss'] }} Output from running Cucumber: {{ d['search.feature|cuke'] }} <h2>Rails App Source</h2> Here is the source code for the controller class: {{ d['search_controller.rb|pyg|inlinecss'] }} And here is the ERB template for the view: {{ d['index.rhtml|pyg|inlinecss'] }} <h2>Screenshots</h2> Screenshots (click to enlarge)<br /> {% for x in d['a'] %} <a href="../../artifacts/{{ d['a'][x] }}"> <img src="../../artifacts/{{ d['a'][x] }}" width="200px" /> </a> <br /> {% endfor %} <h2>Colophon</h2> {{ d['developer.html|pyg|inlinecss'] }}
  • End-User Documentation ✤ PDF Format for ease of distribution and printing (could be a book). ✤ Explain in terms of end-users workflow ✤ Live screenshots ✤ Since this is automated, we could run per-customer for personalized branding. Even per-user based on their personal preferences or available features. ✤ Backed by Cucumber specs so we know when something breaks.