Dexy on rails

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 ﬂexible 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)

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 workﬂow ✤ 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.

Dexy on rails

by ananelson on Nov 06, 2010

Accessibility

Categories

Tags

Upload Details

Usage Rights

1 Embed 1

Statistics

Dexy on rails — Presentation Transcript