Permalink
Browse files

Fixes and upgrades.

* Zero-conf support.
* Rails 3 and Rails 2 generator support.
* Ruby 1.9 compatibility.
* Doc clean-up.
  • Loading branch information...
1 parent 2616edb commit 430204526c637f15ec378ddefe5d85f96cfa821d Alex Fortuna committed Jul 10, 2011
View
@@ -1,14 +1,14 @@
+# General Ruby, sorted by first letter.
.old*/
*-old*
-*-old*/
/*.patch
.proto-*
-.proto-*/
-*.rbx
.ref*
-.ref*/
-/#*.txt
+# Project-specific.
/a.rb
+/dev/
/doc/
/pkg/
+/README.html
+/.rvmrc
View
@@ -4,39 +4,70 @@ Rails Debug Toolkit
Introduction
------------
-`rails_dt` gem gives you `DT.p()` method you can use anywhere in your project to print variable dumps, debug messages etc.
+`rails_dt` gem gives you `DT.p()` method you can use anywhere in your project to print your debug messages.
-It's similar to Ruby's native `p()` with output being sent to browser, console and log.
+It's somewhat similar to Ruby's native `p()` with output being sent to log, console and web.
+For example, `DT.p "Hello, world!"` invoked in `RootController` will give you a:
-Setup
------
+ [DT app/controllers/root_controller.rb:3] Hello, world!
- $ gem sources --add http://rubygems.org
- $ gem install rails_dt
-In your application root, do a:
+The Ideas Behind It
+-------------------
+
+* Debug message printer must **not require initialization**.
+* Debug message printer must be **nothing else**, but a debug message printer.
+* Debug message printer must be simple and invoked **always the same way** regardless of where you call it from.
+* Debug message printer calls must be **clearly visible** in the code.
+* Debug message printer must **print its location in code** so you can find and modify/remove it as easy as possible.
+
+
+Express Setup (Rails 3)
+-----------------------
+
+In your `Gemfile`, add:
+
+ gem "rails_dt"
- $ script/generate rails_dt
+Then do a `bundle install`.
-Follow the instructions the generator gives you (they are listed below):
+This gives you an express (zero-conf) setup, which outputs messages to log, `log/dt.log` and console.
+
+
+Express Setup (Rails 2)
+-----------------------
+
+ $ gem sources --add http://rubygems.org
+ $ gem install rails_dt
In your `config/environment.rb`, add:
config.gem "rails_dt"
+
+Setting Up Web Output (Both Rails 3 and Rails 2)
+------------------------------------------------
+
+In your application root, do a:
+
+ $ rails generate rails_dt # Rails 3
+ $ script/generate rails_dt # Rails 2
+
+Follow the instructions the generator gives you then. They are listed below.
+
Inside your `ApplicationController` class, add:
handles_dt
-In your `app/views/layouts/application.html.erb` `<head>` section, add:
+Inside your `app/views/layouts/application.html.erb` `<head>` section, add:
<%= stylesheet_link_tag "dt" %>
-Somewhere at the end of your `app/views/layouts/application.html.erb` `<body>` section, add:
+Inside your `app/views/layouts/application.html.erb` `<body>` section, add:
<div class="DT">
- <%= DT.to_html %>
+ <%= DT.web_messages_as_html %>
</div>
@@ -45,9 +76,13 @@ Checking Setup
Somewhere in your `app/views/layouts/application.html.erb`, add:
- <% DT.p "hello, world" %>
+ <% DT.p "hello, world!" %>
-Refresh a page that uses this layout. You should see "hello, world" beneath your main page content.
+Refresh the page. You should see "hello, world!":
+
+* In your application log.
+* In `log/dt.log`.
+* On the web page, if you've set it up (see above).
Debugging...
@@ -89,8 +124,36 @@ See it in action:
### ...Anything! ###
-To conclude it, `DT.p` is the universal method you can print your debug messages with.
+Just use `DT.p` anywhere you want.
+
+
+Customizing Output Format
+-------------------------
+
+Create a sample initializer, by doing a:
+
+ $ rails generate rails_dt # Rails 3
+ $ script/generate rails_dt # Rails 2
+
+In `config/initializers/dt.rb` you'll see something like:
+
+ # Customize your DT output.
+ #DT.log_prefix = "[DT <%= file_rel %>:<%= line %>] "
+ #DT.console_prefix = "[DT <%= file_rel %>:<%= line %>] "
+ #DT.web_prefix = '<a href="txmt://open?url=file://<%= file %>&line=<%= line %>"><%= file_rel %>:<%= line %></a> '
+
+Uncomment and edit lines appropriately. Restart server for changes to take effect.
+
+Values are in ERB format. The following macros are available:
+
+* `file` -- full path to file.
+* `file_base` -- file base name.
+* `file_rel` -- file name relative to Rails application root.
+* `line` -- line number.
+
+You can also disable particular output target by setting its prefix to `nil`:
+ DT.console_prefix = nil # Disable console output.
Feedback
View
@@ -15,6 +15,7 @@ begin
"[A-Z]*.*",
"*.gemspec",
"generators/**/*",
+ "lib/generators/**/*",
"lib/**/*.rb",
"init.rb",
]
@@ -24,22 +25,44 @@ rescue LoadError
end
desc "Rebuild gemspec and package"
-task :rebuild => [:gemspec, :build]
+task :rebuild => [:update_generator2, :gemspec, :build]
desc "Push (publish) gem to RubyGems (aka Gemcutter)"
task :push => :rebuild do
# Yet found no way to ask Jeweler forge a complete version string for us.
vh = YAML.load(File.read("VERSION.yml"))
version = [vh[:major], vh[:minor], vh[:patch]].join(".")
- pkgfile = File.join("pkg", [GEM_NAME, "-", version, ".gem"].to_s)
+ pkgfile = File.join("pkg", "#{GEM_NAME}-#{version}.gem")
system("gem", "push", pkgfile)
end
desc "Generate rdoc documentation"
Rake::RDocTask.new(:rdoc) do |rdoc|
rdoc.rdoc_dir = "doc"
rdoc.title = "DT"
- rdoc.options << "--line-numbers"
- rdoc.options << "--inline-source"
+ #rdoc.options << "--line-numbers"
+ #rdoc.options << "--inline-source"
rdoc.rdoc_files.include("lib/**/*.rb")
end
+
+desc "Update Rails 2 generator files with Rails 3 generator files"
+task :update_generator2 do
+ puts "Updating Rails 2 generator files..."
+ fns = FileUtils.cp_r Dir["lib/generators/rails_dt/{USAGE,templates}"], "generators/rails_dt"
+ puts ": ok (fns:#{fns.inspect})"
+end
+
+desc "Compile README preview"
+task :readme do
+ require "kramdown"
+
+ doc = Kramdown::Document.new(File.read "README.md")
+
+ fn = "README.html"
+ puts "Writing '#{fn}'..."
+ File.open(fn, "w") do |f|
+ f.write(File.read "dev/head.html")
+ f.write(doc.to_html)
+ end
+ puts ": ok"
+end
View
@@ -1,4 +1,5 @@
---
-:patch: 1
:major: 0
:minor: 1
+:patch: 2
+#:build: pre1
View
@@ -0,0 +1,11 @@
+Description:
+ Generate files needed for DT web output.
+
+Example:
+ rails generate rails_dt
+
+ This will create:
+
+ * `config/initializers/dt.rb`
+ * `public/stylesheets/dt.css`
+
@@ -0,0 +1,2 @@
+
+WARNING: `USAGE` and `template/*` files are updated with respective files from Rails 3 generator every time gem is rebuilt. Do not edit these files here.
@@ -1,5 +1,4 @@
-#class SessionGenerator < Rails::Generator::NamedBase # <-- was
-class RailsDtGenerator < Rails::Generator::Base
+class RailsDtGenerator < Rails::Generator::Base #:nodoc:
def manifest
record do |m|
m.file "stylesheets/dt.css", "public/stylesheets/dt.css"
@@ -1,23 +1,20 @@
-Finalizing DT installation
-==========================
-
-In your `config/environment.rb`, add:
-
- config.gem "rails_dt"
+Setting Up Web Output
+=====================
Inside your `ApplicationController` class, add:
handles_dt
-In your `app/views/layouts/application.html.erb` `<head>` section, add:
+Inside your `app/views/layouts/application.html.erb` `<head>` section, add:
<%= stylesheet_link_tag "dt" %>
-Somewhere at the end of your `app/views/layouts/application.html.erb` `<body>` section, add:
+Inside your `app/views/layouts/application.html.erb` `<body>` section, add:
<div class="DT">
- <%= DT.to_html %>
+ <%= DT.web_messages_as_html %>
</div>
Happy debugging!
+
@@ -1,4 +1,4 @@
# Customize your DT output.
-#DT.web_prefix = '<a href="txmt://open?url=file://<%= file %>&line=<%= line %>"><%= file_rel %>:<%= line %></a> '
+#DT.log_prefix = "[DT <%= file_rel %>:<%= line %>] "
#DT.console_prefix = "[DT <%= file_rel %>:<%= line %>] "
-#DT.log_prefix = DT.console_prefix
+#DT.web_prefix = '<a href="txmt://open?url=file://<%= file %>&line=<%= line %>"><%= file_rel %>:<%= line %></a> '
Oops, something went wrong.

0 comments on commit 4302045

Please sign in to comment.