スマートな検索ができるRDocを自分のプロジェクトでも使う方法

はじめに

先日エントリーに書いた「Rails Searchable API Doc」のような、便利なRDocを自分のプロジェクトにも適用したい。 それを可能にするためのGemパッケージ「sdoc」がRails Searchable API Docの作者から提供されています。

これはさっそく使ってみたいと思います。

インストール

githubからインストールします。
jsonとrdocの新しいバージョンを要求されますのでインストールしておきます。

sudo gem install rdoc
sudo gem install json
sudo gem install voloko-sdoc --source http://gems.github.com

これでsdocというコマンドが実行できるようになりました。
sdocはrdocにSHTMLというフォーマットを追加してラップしただけのもののようです。

ちなみにRDocの2.4からだと思うのですがデフォルトのテンプレートがDarkFishというちょっとクールなものに変わっているみたいです。あんまりRubyっぽくないデザインです。

使い方

使い方は非常に簡単です

sdoc ディレクトリ名

と実行すればdocフォルダを作成しその中にドキュメントのHTMLを作成してくれます。

Railsのプロジェクトをドキュメント化したい場合、プロジェクトフォルダ内で

sdoc . -o doc/s_app -U -x vendor -x test -x doc -x tmp -x script -x public -x log -x config

と実行すればOKです。

無視するディレクトリは-xオプションで指定します。

Rake化

単純なRakeタスクにしておいても良いでしょう。

Railsのプロジェクトのlib/taskにsdoc.rakeというファイルを生成して、以下のようにシェルを実行する記述をします。

# lib/task/sdoc.rake
namespace :doc do
  namespace :sdoc do
    desc "Generate SDoc Documentation"
    task :app do
      output = 'doc/s_app'
      ignores = %w{vendor test doc tmp script public log config}
      rm_rf output
      option_exclude = ignores.map{|i| "-x #{i}"}.join(" ")
      sh "sdoc . -o #{output} -U #{option_exclude}"
    end
  end
end

で、Rakeタスクを実行です。

rake doc:sdoc:app

で、ドキュメントをdoc/s_appに生成します。

rdoc-documentation

どうですか？サーチャブルなRDocが自分のプロジェクトにも適用されました！
これはがんばってコメントを書こうというモチベーションにも繋がります！素晴らしい！

バグ

素晴らしいと喜んでいたのも束の間、バグを見つけました。（2009-04-03現在）

ドキュメントのテンプレートの中に「%charset%」という置き換えされない文字列がありました。
そうです文字コード指定ができないので、日本語が化け化けです。

大したバグじゃないのでGithubでフォークして直してみました。
本体にプッシュ要求する方法を知らないのでどうしたらいいのだろうか・・？英語も書けないしなー。だれかテーチミー。

直したdiff http://github.com/func09/sdoc/commit/820e29a25efc7957d25dda4d128cae9f2e20844d

参考ページ

さいごに

当初はsdocを使いたいというよりも、RDocのテンプレートの書き方を知りたいと思っていろいろ探したんですが、いまいち良くわからなかった。テンプレートとフォーマットの違いって何だろう？

調べながらRDocのソースを読んでいると、やっぱすごい人のソースはすごいなぁと。こういうメジャーなライブラリのひとつやふたつ隅から隅まで読んでみる、なんてことしてみたいが・・。

Posted in ruby, ruby on rails, 日記 at 4月 3rd, 2009. No Comments.

rspec-railsでテスト結果を見やすくする

はじめに

The Rails Wayを読了しました。 Railsの本は出版されたら大抵買って読むようにしているのですがその中でもかなり良著だったと思います。 これから読む人はRailsアジャイルによるWebアプリケーション入門の後くらいに読むと良いですね。

さて、Rails Wayの素敵な点はテストに結構なページを割いているという点です。 Rails標準のテストとRspecによるテストにそれぞれ章だててあり、ページ数にすると60Pを超えます。 本当はRspecだけで一冊書いてほしいくらいなんですが、それでも今日本語で読める本としては一番多いと思います。

Rspecの結果表示

rake specでもscript/autospecでもいいんですが、何も考えずに使っていると下の画像のようになります。

e9d34049a45293d49131e67dcf884f90

ま、これでもいいっちゃいいんですが フォーマットを買えてリスト表示（specdoc）にしたいなぁと思いました。

spec -cfs spec/hoge_spec.rb

こうオプションを渡した時みたいにね。

spec/spec.opts

specフォルダの中にspec.optsというファイルがあります。こいつの内容を見ると

--colour
--format progress
--loadby mtime
--reverse

おー、見覚えのある文字列が。。specコマンドに渡せるオプションをここに書けばフォーマットも変えることができそう。

--colour
--format specdoc
--loadby mtime
--reverse

こう書き換えたら・・

9271e70b85e8ca0f662ca3ee02a50f17

こうなりました。

こっちの方がいいっすね。

Posted in ruby on rails, 日記 at 3月 30th, 2009. No Comments.

RailsのAPIをスマートに調べられるRails Searchable API Docが便利な件

どんなツール（プログラミング言語、フレームワーク）でも、リファレンスを上手く引けなければ、ツールを使いこなすことはできない。

日々Railsによる開発をしている皆様方におかれましては、ブラウザのアドレスバーに「api」と入力した瞬間「api.rubyonrails.org」が補完されていることと思います。

こんな風に

apiをアドレスバーに入れると

http://api.rubyonrails.org/

は、Ruby on RailsのAPIを網羅したRails開発において欠かす事のできないページですね。
内容も丁寧でわかりやすいんですが、APIが探しにくいという致命的な欠点がありました。

今まではブラウザのページ内検索を駆使してがんばってきたのですが、そんな努力とも今日でお別れです。

Rails Searchable API Doc
http://railsapi.com/
http://railsapi.com/doc/v2.3.2/

見慣れたAPIページの使いにくいフレームの代わりに、スマートな検索を実現するサイドバーが提供されています。

Rails Searchable API Doc

  • クラス、モジュール別の階層表示
  • スマート検索
  • 過去に検索した項目を表示（Safariのみ）
  • ファイル検索
  • ネームスペースによる絞り込み
  • キーボードナビゲーション

といった機能が提供されており、非常に快適にRailsの膨大なAPIの中からお目当てのメソッドを検索できますよ！

超おすすめ。

Posted in ruby, ruby on rails, Webサービス, 日記 at 3月 27th, 2009. No Comments.

Rails 2.3のApplication Templateで煩わしい初期設定とはおさらばする！

はじめに

Rails2.3.1が出ていたので、リリース情報を読み返していたらApplication Templateという素敵機能が2.3から使える事がわかった。

Rails2.3リリースノート訳

Railsを止められない理由の一つに、プロジェクトを作り始めてから実際に動作するまでが非常にラクチンだという事がある。

例えば：

% rails Todo
% cd Todo
% script/generate scaffold todo title:string finished:boolean
% rake db:migrate
% script/server

このたった5行のコマンドで簡単なToDoアプリが出来上がっている。

しかしモックならまだしも実運用するためのプロジェクトを作ろうと思ったら、必要なプラグインを入れたり、いつも使う拡張コードを書いたり、さすがのRailsでも毎回粛々とした作業は必要だ。

コマンド一発でいつも使うプロジェクトのセッティングまでしてくれればいいのに！そんなRailsエンジニアが誰しも望んでいたであろう機能が「Application Template」だ。 Read More…

Posted in ruby, ruby on rails, 日記 at 3月 6th, 2009. No Comments.

Ruby on Rails2.3RC1のNested Object Forms を試してみた

気づいたらRails2.3RC1が出てました。 こないだ2.2がでたばかりなのに、忙しいですね。。

http://guides.rubyonrails.org/2_3_release_notes.html

Nested Object Formsという機能が追加されていまして、 その名前の通り、入れ子状態のモデルのフォームを作るための機能らしいです。

親モデルのフォーム内で、子モデルの編集を展開できるようにするのは、いままでだとちょっと面倒だったので願ったり叶ったりですね。

gem を最新の状態に

rackが0.9以上じゃないとダメだと怒られたので、アップデートしておきましょう

# rackを最新版にしておきます
sudo gem install rack

# 僕は念のために全部updateしました
sudo gem update

プロジェクト作成

railsのプロジェクトを作って、最新版でフリーズする

$ rails nested_sample
      create
      create  app/controllers
      create  app/helpers
      create  app/models
      create  app/views/layouts

$ cd nested_sample

$ rake rails:freeze:edge

scaffold

ToDoリストの簡単なアプリをScaffoldします

% script/generate scaffold user name:string
      exists  app/models/
      exists  app/controllers/
      exists  app/helpers/
      ....

% script/generate scaffold todo user_id:integer title:string due:date is_finish:boolean
      exists  app/models/
      exists  app/controllers/
      exists  app/helpers/
      ...

% rake db:migrate
(in /Users/haga/Desktop/nested_sample)

モデルで関連を設定する

  • Userにhas_many :todos
  • Todoにbelongs_to :user

を設定する。 その際にaccepts_nested_attributes_forというメソッドを使ってNested Object Formsを利用できるようにしておくこと。

% emacs app/models/user.rb

class User < ActiveRecord::Base
  has_many :todos
  accepts_nested_attributes_for :todos, :allow_destroy => true
end
% emacs app/models/todo.rb

class Todo < ActiveRecord::Base
  belongs_to :user
end

Userモデルのフォームを変更

app/views/user/edit.html.erbを変更します。 fields_forを使って、子todoをeachしていますね。

<h1>Editing user</h1>

<% form_for(@user) do |f| %>
  <%= f.error_messages %>

  <p>
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </p>

  <ol>
  <% f.fields_for :todos do |todo_form| %>
    <li>
      <p>
        <%= todo_form.label :title %><br />
        <%= todo_form.text_field :title %>
      </p>
      <p>
        <%= todo_form.label :due %><br />
        <%= todo_form.date_select :due %>
      </p>
      <p>
        <%= todo_form.label :is_finish %><br />
        <%= todo_form.check_box :is_finish %>
      </p>
    </li>
  <% end %>
  </ol>

  <p>
    <%= f.submit "Update" %>
  </p>


<% end %>

<%= link_to 'Show', @user %> |
<%= link_to 'Back', users_path %>

script/consoleでユーザーとToDoを追加

ちょっとずるして、script/consoleでユーザーとToDoの準備をば

$ script/console
>> u = User.create :name => 'func09'
=> #<user id: 2, name: "func09", created_at: "2009-02-02 04:11:11", updated_at: "2009-02-02 04:11:11">
>> u.todos.create :title => "test 1", :due => 2.day.since, :is_finish => false
=> #<todo id: 3, user_id: 2, title: "test 1", due: "2009-02-04 04:13:01", is_finish: false, created_at: "2009-02-02 04:13:01", updated_at: "2009-02-02 04:13:01">
>> u.todos.create :title => "test 2", :due => 1.day.ago, :is_finish => true
=> #<todo id: 4, user_id: 2, title: "test 2", due: "2009-02-01 04:13:13", is_finish: true, created_at: "2009-02-02 04:13:13", updated_at: "2009-02-02 04:13:13">

確認

できた！！

e382b9e3838ae38383e38397e382b7e383a7e38383e38388-2009-02-02-13-14-49

Posted in ruby, ruby on rails, 日記 at 2月 2nd, 2009. No Comments.

Fixtureのhas_manyでこんな書き方したい

http://ar.rubyonrails.org/classes/Fixtures.html

fixtureの中でbelongs_toは便利だけど
has_manyの時に、HABTMでの書き方みたいのできないんですか？
できたらいいのに。

# test/fixture/user.yml

taro:
  name: 太郎
  statuses: taro_status_0, taro_status_1, taro_status_2
# test/fixture/status.yml

taro_status_0:
  message: おはよう

taro_status_1:
  message: こんにちは

taro_status_2:
  message: こんばんは
Posted in ruby, ruby on rails at 1月 25th, 2009. No Comments.

URLをわりと短くするサービス「shur.in」のソース公開しました

URLをわりと短くするサービス http://shur.in/

URLをわりと短くするサービス「shur.in」を作った。 http://www.func09.com/wordpress/archives/237

のソースコードを公開しました。

shur – Google Code http://code.google.com/p/shur/

数時間で作ったものなので大したもんじゃないけど Google CodeかGithubでコードを公開する練習として。 Githubの方はまだこれからです。

Posted in ruby on rails, Webサービス at 1月 22nd, 2009. No Comments.

Capistranoとscript/process/reaperの実行権限

Capistranoでデプロイするときに途中で止まってしまう現象に悩まされていました。

** [out :: your.host.name] sudo: /home/haga/deploy/xxxxx/current/script/process/reaper: command not found

こんな感じで止まる

デプロイ自体は完了しているみたいだったので無視してたのですが

after :deploy, 'hogehoge:foo'

みたいなdeploy後のコールバックを実行できなくて 毎回手でやるのが面倒だった

原因は script/process/* に実行権限が無いからだった。 何故かcheckout時に実行ファイルじゃなくなっているみたい。

そんな場合は

svn:excutable

を利用して、実行ファイルとしてSVNにコミットする。

svn propset svn:executable ON script/process/*

これでOK

Posted in ruby, ruby on rails at 1月 9th, 2009. No Comments.

[rails] ユーザーのパスワード忘れ処理を簡単に生成してくれるプラグインforgot_password ( with Restful-authentication)

はじめに

Railsとrestful-authenticationの組み合わせで、パスワード忘れの機能を実装するにあたって、いろいろと参考になるものを探していたところ、簡単に機能を実装できるプラグインがあったので紹介。

forgot_passwordプラグイン
http://github.com/greenisus/forgot_password/tree/master

restful-authenticationを使う事前提で、script/generate forgot_passwordというジェネレータでちゃちゃっとパスワードを忘れた人用のページを作ってくれます。実際にやってみます。

準備

まずはプロジェクトのインストールから

% rails forgot_password_sample
% cd forgot_password_sample/

つづいてプラグインのインストール。gitコマンドが必要です。

% script/plugin install git://github.com/technoweenie/restful-authentication.git
% script/plugin install git://github.com/greenisus/forgot_password.git

そして、認証とパスワード忘れのジェネレーターを実行。

% script/generate authenticated --include-activation user sessions
% script/generate forgot_password forgot_password user

forgot_passwordプラグインによって、以下のファイルが追加・編集されている

  • 追加ファイル
    • db/migrate/xxxxxxxxxxxxxx_create_forgot_passwords.rb
    • app/models/forgot_password.rb
    • app/models/forgot_password_mailer.rb
    • app/controllers/forgot_passwords_controller.rb
  • 修正ファイル
    • config/routes.rb

Read More…

Posted in ruby, ruby on rails at 11月 18th, 2008. 3 Comments.

[rails] restful-authenticationの使い方　基本編

はじめに

Railsでの認証機構はrestful-authenticationで決まりらしいのですが、いざ自分で新しい機能を実装しようと思うとなかなか骨があってどう組んで良いものか悩んでしまう。

ユーザー認証のあるサービスには欠かせないであろうパスワードを忘れた人への対策処理を実装してみようと思うのだけど、えらく長くなりそうなので、とりあえず基本的なrestful-authenticationの使い方を。

準備

  • railsのプロジェクト「auth_sample」を生成
  • restful-authenticationのインストール
  • aasmのインストール
  • script/generate authenticated

[c] // プロジェクト生成 % rails auth_sample % cd auth_sample

// プラグインインストール % script/plugin install git://github.com/technoweenie/restful-authentication.git % script/plugin install git://github.com/rubyist/aasm.git

// 雛形の生成（メールアクティベートとaasmによる状態管理を有効にしておく） % script/generate authenticated –include-activation –aasm user sessions

[/c]

続いて

  • config/environment.rbにuserモデルのオブザーバーを定義
  • config/routes/rb
    • /activateのルートを設定
    • usersのresourcesにsuspend,unsuspend,put,purgeを追加
  • AuthenticatedSystemのインクルード

[ruby]

config/environment.rbに追加

config.active_record.observers = :user_observer

config/routes.rbに追加

map.activate ‘/activate/:activation_code’, :controller => ‘users’, :action => ‘activate’, :activation_code => nil map.resources :users, :member => { :suspend => :put, :unsuspend => :put, :purge => :delete }

app/controllers/applications.rbに追加

include AuthenticatedSystem

＃

[/ruby]

を追加しておく。

さらに、このままではaasm用のクラスを読み込めないので
vendor/plugins/restful-authentication/rails/init.rb
に下記の追加

[ruby]

vendor/plugins/restful-authentication/rails/init.rb

この行を追加してaasmを読み込む

require File.join(File.dirname(FILE), “..”, “lib”, “authorization”, “aasm_roles”) [/ruby]

ここまでで、基本的なrestful-authenticationの準備は終わり。

rake db:migrateして、サーバを起動し

  • 新規登録
    • http://localhost:3000/signup
  • ログイン
    • http://localhost:3000/login
  • ログアウト
    • http://localhost:3000/logout

次回はパスワード再設定を実装してみます

Posted in ruby, ruby on rails at 11月 15th, 2008. No Comments.

« Older Entries

Newer Entries »