2010年11月06日

Sphinx 1.1preの検索機能の修正

Magnified (8/365)

Sphinxの検索インデックス作成処理をハックして、日本語を通すようにしよう!というのを以前からちょこちょこっとやっているのですが、いろいろ忙しくしている間に、いろいろ不具合とか見つけてくれたりしてくれる人がいたり(http://d.hatena.ne.jp/hokorobi/20101030/1288419035)、ありがたい流れになってきています。というか放置状態ですみません。今、Sphinx翻訳ハッカソン中なので、時間をとっていろいろコード修正とかをしました。また、言語を追加できるAPIとして整備して、本家に提案してみたところです。ほんとはドイツ語のステマーでも実装してサンプルにしてみると意義がわかりやすくはなるんでしょうけど、ドイツ語(一応大学でちょっとやったが)のステマーを実装するのは大変なので・・・誰かやってくれると助かる感じ。というかPython実装とかどっかにありそうなんだけどね。

APIの使い方のイメージはこんな感じになっています。例えば、フランス語(コードfr)の場合です。

from sphinx.search_languages import SearchLanguage

class SearchFrench(SearchLanguage):
    lang = 'fr'

    def init(self):
        self.stopwords = set([ストップワードこれはJavaScript側にもコピーされます])
        self.js_stemmer_stemmer = """JavaScript側で動く、ステマーのプログラム"""

    def split(self, sentence):
        """ここで、スプリッターを実装します。デフォルトはスペース区切り。"""

    def stem(self, word):
        """ここでPythonのステミング処理を実装します。"""

    def word_filter(self, stemmedword):
        """ここでインデックスに登録するかどうかの判定をします。"""

def setup(app):
    app.add_search_language(SearchFrench)

ちなみに、リポジトリはここ(https://bitbucket.org/shibu/sphinx/overviewです。

hokorobiさん、いろいろ指摘していただいてありがとうございます。

posted by @shibukawa at 15:50 | Comment(168) | TrackBack(0) | Python はてなブックマーク - Sphinx 1.1preの検索機能の修正

2010年10月03日

Bitbucket買収?そもそもそれ何?という人のためのBitbucket紹介

bitbucket

9/29の水曜日に、Atlassian社がBitbucketを買収するというニュースがありました。これにより、今まで有料だったようなサービスが無料で提供されるようになりました。買収したのは、Jiraなどの開発ツールで有名な会社です。とはいえ、Python界隈の人以外にはあまり注目されてこなかったサイトだとは思うので、BitBucketを紹介します。僕はソースコード管理ではメインで使っています。

買収されたBitbucketって何ですか?

Bitbucketは何者か?一言で言えば、Mercurial版のgithubです。以上。

これで分かる方はここの説明はすっとばしてくれて構いません。いわゆる、プロジェクトのホスティングサービスの一つです。ソフトウェア開発に必要な仕組みが備わっています。

バージョン管理

ソフトウェア開発をやるからには、バージョン管理はやっていますよね?中にはフォルダの中に人名のフォルダを作ってやっている人もいるようですが・・・BitbucketはMercurialというシステムを使います。さまざまなホスティングサービスがあり、それぞれサポートしているバージョン管理のシステムが違います。今時人気なのは分散バージョン管理です。

分散バージョン管理固有の機能として、他の人の作ったプロジェクトの複製が簡単に作れるようになっています。例えば、このSphinx日本語検索対応と、Sphinxドキュメント翻訳は、Sphinx本体を分岐させて作ったプロジェクトです。複製は簡単。ページの上の方にあるfolkボタンを押すだけです。複製したあとも、元のプロジェクトの最新バージョンを取り込んだり、他の人が分岐して作ったパッチをまとめて取り込んだりできます。

他のホスティングサービスは何を使っているんでしょうか?

  • Mercurial: Bitbucket, Sourceforge, CodePlex, GoogleCode
  • Git: github, Sourceforge
  • Bazaar: launchpad

圧倒的ではないか我が軍は

ということで、Mercurialは覚えておいて損はないと思います(僕の知らないサービスもあるかもしれませんけど。あったらこっそり教えてください)。

差分ビューア

バージョン管理の一部といえば一部ですが、ウェブ上で、それぞれの差分の更新情報を確認することができます。

一般的なビューアは行ごとの差分だけの表示のものも多いのですが、行の中の違う箇所も便利に見つけてくれます。微妙に誤字を修正しました、みたいなケースは行ごとの差分だけ見ても見落としがち(どこを直したのかわからない)ことが多いのですが、Bitbucketなら、多い日も少ない日も安心です。

Wiki

オンラインドキュメントといえばWiki。Bitbucketももちろんサポートしています。Wikiの文法としては、様々に分岐したWikiフォーマットを統一するために作られたというCreole記法が採用されています。まぁ、あんまり使ってないのですが・・・

Issueトラッカー

Trac並にシンプルなやつが付いています。なお、バージョン、マイルストーン、コンポーネントなどの項目は自分で追加したりもできます。Ubuntuみたいに、バグレポートと、Issueトラッカーが別システムになっていて、途中にトリアージを行う専門チームがいるような大規模案件には向かないと思います。ちょっとしたToDoとか、他の人からパッチをもらう情報交換手段(ファイルが貼り付けられる)として使う感じですね。

管理ツール

シンプルに見えますが結構色々できます。

  • リポジトリを公開リポジトリにしたり、非公開にしたりできる
  • Wiki/IssueトラッカーをOFFにしたり、メンバー限定にしたりできる
  • Issueトラッカーに変更があったときにメールしたりできる
  • ソースに変更があったときにTwitterなどにツイートしたり、どこかにメールしたり
  • 読み/書き/管理 権限を追加したり外したりできる

Sphinx-Users.jpでは、この最後のアカウント管理を利用しています。ウェブサイト(Sphinxでできている)のソースはまるごとBitbucketに載せています。「ページを作りたい」と手を挙げてくれた人がいたら、bitbucketのアカウントを作ってもらって、IDを教えてもらい、管理画面のWritersの所に追加しておしまい。なお、1時間に一回、このリポジトリからソースをpullして、ビルドするような仕組みをさくらインターネットのサーバ上に作ってあります(なんてことはないシェルスクリプトをcronで動かしているだけですが)。なので、Writersに登録した人が、手元で修正してpushすればOK。不要になった人の権限も外せますし、別に僕がパスワードの管理とかをする必要もないし、超ラクラク運営をしています。もしパスワードの使い回しとか、公開FTPサイトに乗っけちゃったりとか、20世紀ぐらいでしか許されないようなレトロな共有サーバ運営している人がいたらオススメしたいです。

そういえば、前は自分のドメインの下で動いているように見せかけるような設定ができたはずですが、今はどうなっているんだろう?

で、買収されて何が変わったの?

容量制限がなくなりました

今までは無料で150MBぐらいだったかな?まぁ、テキスト主体ではそれでも個人レベルでは十分な量でしたが・・・今では無限大です。

プライベートリポジトリが作り放題です

今までも無料プランで1つは可能でした。今ではいくらでも作れます。本を書いたり、いろんな原稿を書いていたりすると、仲間内だけで使えるリポジトリが欲しくなりますが、これで安心です。今取り組んでいる2冊はさっそくBitbukcetに移行しました。

今まではびくびくしながら、Dropboxの中にリポジトリを作って運用とかしてましたが(複数人で同時にコミットするとリポジトリが壊れたりする)、これで安心です。

なお、現在課金対象となっているのは、プライベートリポジトリで一緒にチーム開発を行う人数です。5人までは無料です。10人までの場合は、現在1年間無料キャンペーンをしています。

(10/4補足:キャンペーンは10/3まででした。

今後は積極的に機能拡張されていく模様

開発者数が3倍になって、今後はいっぱい改良していくよ!とアナウンスがありました。今のシンプルなのも好きですけどね。Sphinxのドキュメントをアップするとビルドしてくれたりするようになるとうれしいんですけどねー

Mercurialってどうなの?

とはいっても、気になるは、使用が強制されるMercurialのこと。慣れるとSubVersionよりも簡単です。商用サポートもあるらしいです。ちなみにPythonで書かれていて、Pythonからライブラリとして色々操作することができます。Mercurialをバックエンドにして、Wikiのシステムを作ったりもできます。Python温泉系の人には「まずはimport mercurial」と言っている人もいます。変態ですね。

ただし、バージョン管理システムとしての完成度はBazaarの方が上な気はしています。SubVersionのような、中央管理っぽく動くモードを備えていたり、OS問わず、日本語ファイル名OKだったり、完成度がTortoiseSVN並に高い、WindowsのクライアントのTortiseBZRがあったり・・・もうね、MicrosoftがVisual Source Safe 7.0という名前でリリースしちゃってもいいと思うよ!というぐらいです。僕はコマンドラインで使うので、Mercurialでも別にストレスは感じませんが、やはり人に勧めたり、仕事で使うなら、Bazaarがいいかなぁ、と思ったりもします。

とはいえ、日本語の本も出ていたりしますし、日本語のドキュメントも充実しています。できるPythonプログラマーはみんな持っている?エキスパートPythonプログラミングの中でも使い方の解説があります。サーバなしで、ローカルのファイルの管理にも簡単に使えます。/etc/とか、設定ファイルがあるようなホームディレクトリなどで、$ hg initとタイプして、設定ファイル群をまとめて入れておくのとかオススメです。失敗しても戻せますしね。差分も取れるようになるし。

Mercurialが他の分散バージョン管理システムに比べて圧倒的に優れていると思う点は、タイプのしやすさ。アプリ名はMercurial(水銀/水星/神話のマーキュリー)ですが、コマンド名はhg(水銀の元素記号)。右手と左手の人差し指で1本ずつです!Emacs病やVi病を煩っている人は小指を酷使して疲れていると思うので、Mercurialがオススメです。

初出では、人差し指でなく、親指になっておりました。お詫びして訂正します。

posted by @shibukawa at 03:01 | Comment(192) | TrackBack(0) | Python はてなブックマーク - Bitbucket買収?そもそもそれ何?という人のためのBitbucket紹介

2010年09月29日

Sphinx日本語検索対応の1.0版

Sphinx Statue In Trent Park, London
by GoodImages under CC BY-NC-ND

写真は、イギリスのSphinx Statueというやつだそうで。本当の名前かは知らないけど。

以前に行った、Sphinxの検索の多国語対応ですが、ちょっと修正を加えて、1.0対応しました。Sphinx-Users.jpのぺージのビルドに使うSphinxも、この日本語検索対応版にしました。

MeCab対応の強化とYahoo!形態要素解析対応の削除

基本的な設定は前回から変わっていませんが、今回は、MeCabの対応を強化しました。

mecabライブラリ検索の自動化、ライブラリ関連オプション追加

ctypesにfind_libraryというのがあったので、これを使うようにしました。MacやLinuxであれば、何も設定しなくても(html_search_language='ja'と、html_search_language_option={"type":"mecab"}だけで)、MeCabを読みに行きます・・・はずですが、MacPortsのMeCabを読み込もうとすると、バージョン番号の取得はうまくいくのに、いざ分かち書きをさせるとPythonごと落ちるという事象に悩まされたので、純正のMeCab-Pythonインタフェース(easy_installでは入れられません)が入っていれば、それを使うようにしました。なお、Windowsも、dllが検索パスに入っていればライブラリパスの設定なしで行けるはずです。

前回は"mecab"の時には必ず、mecabの拡張ライブラリ(dll, so, dylibなど)の絶対パスを指定する必要がありましたが、そのlibpathオプションがなくなっています。代わりに以下のオプションが追加になりました。

  • lib: 単独のファイル名、もしくは絶対パス。ctypesで読む場合に利用。省略時は自動検索。
  • dic_enc: 辞書ファイルのエンコード。utf-8, euc-jpなどPythonで使えるコーデック名で指定。省略時はutf-8。
  • dict: 辞書ファイルのパス。標準と違うファイルを利用したい場合に。

Yahoo!形態要素解析の削除

パフォーマンスが悪すぎるために削除しました。

実装してみたものの・・・

MeCabを使わない場合(デフォルト)では、TinySegmenterのPython移植を利用するようになっています。そのため、辞書ファイルなどをダウンロードしなくても日本語分かち書きができるのですが、これ以外の分かち書き(例えば、ひらがな、カタカナ、漢字の境界で分割)も併用して、検索インデックスを増やすなどの対応をする必要がありそうです。

Sphinxでは、make html実行時にsearchindex.jsというインデックスファイルが作られ、Sphinxのファイルを見ているマシンのブラウザ上で検索が行われます。その検索の品質を左右するのが、このインデックス作成です。もちろん、インデックスファイルを配信するので、N-Gramみたいなインデックスが巨大になる方式は使えません。また、CJK言語のためにでかい辞書をバンドルしてもらうのも難しいです。無駄をなるべく減らすというチャレンジは色々できそうです。また、今は単語のありなしだけでしか見てませんが、用語の登場頻度、セクションタイトルでの利用している場合などの重み付けをする、ということも考えられます(Sphinx本体に手を加える必要が出てきますが)。

SphinxのMLに投稿したのは、言語ごとのインデックス作成をできるようにする、というものですが、言語の特徴によって色々なインデックス作成アルゴリズムを選択できる、あるいは組み合わせるようにする、というのがいいのかな、と思っています。具体的には、拡張機能として実装して、組み合わせを設定できるようにする、というものです。

例えば、フランス語やドイツ語などの場合は、アクセント記号を外したインデックスを作成する、といったことが考えられます。現在対応していない言語も、ユニコードの文字種の境目で分割というアルゴリズムを適用すれば、最低限のインデックスは作れるようになると思います。ただ、どれか1つしか使わない、というのではなくて、インデックスの大きさや、対象となる言語、文章によって選べるようにするのがいいと思います。あ、ステミング処理は言語と密接に関連していますけどね。

ということで、今のパッチのまま提案するのではなく、拡張機能として使えるように、ベースとなるインタフェースクラスを用意して、それを継承して登録するという方式のコードにして、それを提案しようと思います。

posted by @shibukawa at 10:03 | Comment(158) | TrackBack(0) | Python はてなブックマーク - Sphinx日本語検索対応の1.0版

2010年08月08日

日本語でSphinxを使う時のストレスを減らす拡張機能

Umeboshi
Taken by mismisimos under CC BY-NC-SA

Sphinxで日本語を書くときに、日本語の途中で改行を入れると、そこに空欄の文字が入ってしまい、ブラウザで見るときにちょっと見た目が悪くなったりします。まぁ、これはSphinxのせいというよりも、ブラウザのせいですが。

あと、Sphinxというか、docutilsは欧米の言語を対象としている仕様のため、太字にしたり、インラインマークアップを使うときには前後にスペースが必要となります。レンダリング後もこのスペースが残ってしまうため、ブラウザで見るとやはり改行と同じ悪さをします。バックスラッシュというか円記号でエスケープしたスペースを挟めばなんとかなりますが、面倒ですよね?

ということで、軽く作ってみたSphinx拡張。テキストノード中の改行やら、テキストノード前後のスペースを削除します。ぱっと見はうまくいっているけど、どこかに悪影響がないかはよく分かってないけど。これをjapanesesupport.pyとか適当な名前で保存して、Sphinxのconf.pyのextensionsに"japanesesupport"を足してください。デフォルトでTrueだけど、この機能をon/offするオプションもあります。

extensions = ['sphinx.ext.todo', 'translation', 'japanesesupport']

japanesesupport_trunc_whitespace = True

翻訳の訳語置き換えとか、これとか、色々作って組み合わせて日本語サポートパッケージとしてまとめたいところ。

def trunc_whitespace(app, doctree, docname):
    from docutils.nodes import Text
    if not app.config.japanesesupport_trunc_whitespace:
        return
    for node in doctree.traverse(Text):
        newtext = node.astext()
        for c in "\n\r\t":
            newtext = newtext.replace(c, "")
        newtext = newtext.strip()
        node.parent.replace(node, Text(newtext))


def setup(app):
    app.add_config_value('japanesesupport_trunc_whitespace', True, True)
    app.connect("doctree-resolved", trunc_whitespace)
posted by @shibukawa at 14:20 | Comment(295) | TrackBack(0) | Python はてなブックマーク - 日本語でSphinxを使う時のストレスを減らす拡張機能

2010年08月01日

LL TigerのLTでRuby on Python(仮)の発表してきました。

219f953

LL Tigerでライトニングトークスに参加してきました。今回はトーナメントの勝ち抜き方式で、今までのLTで見た中で技術的にハイレベルなプレゼンが数多く行われました。我らが"殺伐Python"は、残念ながら2回戦敗退でしたが、その負けた勝負も「言語実装者vs言語実装をだます人」という、刺激的すぎる対戦でした。柴田さんも、良い試合だったと言ってくれました。@moriyoshi, @ymotongpoo、お疲れ様でした!ちなみに写真は昼休み。「shibuya.jsやべぇよ、飲んで勢いでやろうぜ」的なw(清水川さん、写真ありがとうございます)

イベントとしては、並列の話がおもしろいなぁ・・と思いました。上から下まで、コードジェネレータ、DSL、トランスレート・・・さまざまな技術がないとできない世界。そういう言語の実装はやってみたいものの一つです。良い刺激を色々受けることができました。僕も最近は時間がなくて、自分の発表をするイベント、スタッフとして召還されたイベントしか参加してませんでしたが、今回は、発表がなかったとしても楽しめたと思います。

で、僕のプレゼンについて・・・資料だけでは分からない所も多いと思いますので、今回もしゃべり原稿を清書してブログを書こうと思います。初戦はこのプレゼンで勝ち抜けることができました。相手の方のプレゼンも、なかなかおもしろかったけど、あれが動画じゃなくて、実際のインタラクティブなデモだったらもっとギリギリの戦いになっていたと思います。

最初は、メタプログラミングRubyが出版されるのにかこつけて、Rubyとの対決色を出して「Rubyが実行できるんだからPythonの方がメタプログラミングは強力だぜ」みたいなプレゼンにしようかとも思って、調査機関Gに依頼して各言語のメタプログラミング需要を調査したりもしていたのですが、まぁ、そこまであおらなくても十分「Python変態すぐる」みたいなレベルには到達したと思うので、淡々とPythonの説明だけにしました。

slide01続きを読む
posted by @shibukawa at 09:57 | Comment(367) | TrackBack(1) | Python はてなブックマーク - LL TigerのLTでRuby on Python(仮)の発表してきました。

2010年07月30日

Sphinx 1.0リリースパーティを開催しました!

Lego Sonic
Taken by Roomic Cube under CC-BY

先日、Sphinx 1.0リリースパーティを開催しました。元々、1.0は先月の頭には出そうな勢いだったので、大分前に計画をしていました。でも、なかなか1.0がリリースされないので「1.0プレパーティ?」「1.0b2パーティかな?」みたいな感じでとりあえず集まって飲みますか、という感じになっていましたが、偶然にもその日のうちに1.0がリリースされ、翻訳も1.0に合わせた更新を行い、乾杯をすることができました。Georg Brandl氏がSphinxのMLに「リリースしたよー」というメールを出したのは、PyPIにアップされてからちょっと経ってからなのですが、実にそのメールが出て(JST 17:46)から、20分後にリリースを祝って乾杯するという、リアルタイムな飲み会になりました。偶然すぎるw

それはそうと、この飲み会でやりたかったことが2つありました。Sphinx-Users.jpのウェブサイトは文字とスクリーンショットばかりで、裏の人がまったく見えないというか、人の体温を感じないサイトなんですよね。情報系サイトならそれでもいいのですが、やはりコミュニティとして、人の集まる場にしていきたいので、その人肌感覚というか、それをちょっと出したい、というのが一つ目。

それも兼ねて、もう一つやりたかったのは、リリース1.0に向けてのメッセージを発信するということ。それは、オープンソースの活動に一番必要なのはモチベーションであると思うからです。

できあがったのがこれです。

オープンソースでは、直接お金が稼げるわけではありません。「開発をやっていて楽しい」というものがなければ開発は続きません。ライセンスがどうのとか、そういうのは二の次で、やはりモチベーションが一番大事です。モチベーションがオープンソース界を支える通貨だとすれば、開発者に「ありがとう」というのは正当な経済活動と言えます。お世話になってますしね。ちなみに、このページのURLを英語のメーリングリストに投げたところ、開発に関わっている方がTwitterで紹介してくれて、メイン開発者のBirkenfeld氏と、エキスパートPythonプログラミングの著者のTarekがRTしてくれましたし、ちょうどさっき、Birkenfeld氏が「日本に行って君らと会いたいよ」というメールの返信をくれました。

お金以外のものがコミュニティ活動の経済原理だ、といのはThe Art of Community(洋書)でも言っていますし、モチベーションが大事というのは、IT業界を楽しく生き抜くための「つまみぐい勉強法」の肝となる部分でもあります。

みなさんは、お世話になっているソフトウェアの作者の人に、感謝の気持ちを伝えていますか?

ちなみに、トップの写真はネタになる→モチベーションアップから、ネタっぽい画像をチョイスしてみました。Sphinxとは無関係です。

posted by @shibukawa at 02:55 | Comment(48) | TrackBack(0) | Python はてなブックマーク - Sphinx 1.0リリースパーティを開催しました!

2010年05月26日

エキスパートPythonプログラミングできました!

DSC_0588

ゴールデンウィーク後が締め切りのところ、5/6の朝4時ごろまで(清水川さんはロスタイムまで)かかって、ぎりぎりまで修正したり、少しでもいい本にしようと4人でがんばって訳したエキスパートPythonプログラミングができあがりました!訳者およびレビューアの方々には先週末に届きました。正式に本に並ぶのは5/31の予定です。なお、アマゾンだと5/28になっているので、大型書店では今週にでも買えるのかも。

もう既に他の翻訳者の面々がブログに書いていたり、Twitterでがんがん書いていて、ちょいと出遅れましたが、僕も本の紹介をします。

日本語訳者による前書きを書いた(その後みんなで推敲)のですが、この本が良すぎて、書きたいことがふくれあがって増えすぎてしまったので、推敲に出す前にずばっと削除しました。削られた内容を中心にいろいろ加筆しつつ、本書のすばらしい部分を紹介していきます。

Pythonの最新の知識とその適切な使い方が身につく

今でこそ3系への移行ということで、大きな変化の真っ最中ですが、Pythonという言語そのものは後方互換性も高く、一度学んだ知識をアップデートしなくても、あまり不便を感じないですごすことができます。また、新しい文法というのは、たんなるシンタックスシュガーではなく、新しい開発のパラダイムを導入するようなものまであるため、使ってみると便利だけど二の足を踏んでいる、という人も多いと思います。そんな中、高度な文法に限定して、新しい知識を系統立ててきちんと学べる本というのは他の言語を見回してもそれほど見つかりません。

なかなかぱっとやりにくい(勇気のいる)、パッケージの開発、PyPIへのアップロードについても説明されています。gemがよくわからないので、誰かRubyの人で同じような本書いてくれないかな・・・

エンジニアとしての土台となる知識が身につく

開発プロセス、ドキュメントの書き方、ユニットテスト、プロファイリング、最適化など、言語によらないけど、きちんとした仕事をしていくには必要となる知識がつまっています。個人的にSphinxの翻訳とかコミュニティをやっていることもあり、ドキュメントの章にとても惹かれました。この本の翻訳に興味を持ったきっかけもここです。テクニカルドキュメントを書くための7つのコツはおすすめ。↓で10章は公開していますのでどうぞ。

Pythonの開発のライフサイクルを知ることができる

Pythonには開発のライフサイクルを支えるツールがたくさんあります。本書では、egg, PyPI, virtualenv, buildout, Sphinx, Mercurial, Tracなど、現在のPython界で良く使われるツール群の適切な使い方、連携の仕方が、ライフサイクルの各段階ときちんと呼応するように書かれています。単に文法に詳しい、というだけではなく、実践的な意味で「Pythonに精通している」と言えるような知識がまとめて手に入ります。

もしもタイトルを自由に選ぶことができるのであれば、「達人プログラマー」という言葉の入ったタイトルにしたいような内容になっています。

いい意味で突き抜けている

この本の最初はものすごくインストールの説明が丁寧です。Windows, Mac, Linuxについて、それぞれバイナリパッケージ、ソースコードからのインストールを説明をしていたりします。ですが、次の瞬間、「Pythonにあう開発環境はVimです」と、vimrcの解説が始まったりしますw

翻訳時にちょっと話題になった、「ウォーターフォールの開発プロセスは、分析→設計→TDD」というのは、日本的には???という感じかもしれません。TDDはアジャイルと同じ文脈で語られるので。でも、海外ではアジャイルがウォーターフォールよりもシェアが高くなっているという話もあるし、海外ではもうTDDはメジャーなのかもしれません。

日本語版の方が良い?

僕自身Python歴はそろそろ8〜9年ぐらいです。かなり書いて、そこそこPythonの知識には自信がありましたし、PyPIにアップロードとかもしていましたが、とくに開発ツールのベストプラクティスという意味ではかなり未経験な部分がこの本の中に数多くありました。また、共訳者の人たちの知識も豊富なため、さまざまな学びを得ることができました。日本語版オリジナルで、稲田さんが書かれた日本語の章もおすすめです。

なお、日本語版は対象バージョンを2.5系から2.6系にバージョンアップし、説明を更新しました。また、さまざまなサンプルコードなど、細かい部分まで間違いを修正したり、2.7以降の動きについても補足を加えたりして、原著を買った人にもお勧めしたい完成度になったと思います。原著者のTarekも、「日本語版の方が良い」というようなメッセージを寄せてくれました。

ポップ

池袋ジュンク堂のポップも書いてみました。日曜日にお店の方にお渡ししたので、ジュンク堂に並ぶ時にはこれもついているかも。あなたも今日から「蛇遣いエキスパート」というコンセプト?です。Pythonは蛇ではないけど。他の書店のポップも承りますので、もしポップがご入り用な書店の方はメールいただけたら、と思います。

DSC_0591

10章無料公開しています!

原著でもサンプルとしてこの章が無料公開されていますが、日本語版でも同じように公開できることになりました。ウェブ上でも読めますし、PDF、iPadで読めるePubファイルも公開しています。iPadを買われた方は、きっと何か使ってみたくなると思うので、ePubファイルをおすすめですよ?iPad読みやすそうです!(写真は@takabowのご協力によりゲットできました)

DSCF0335
posted by @shibukawa at 20:54 | Comment(227) | TrackBack(1) | Python はてなブックマーク - エキスパートPythonプログラミングできました!

2010年04月10日

引数のカッコが省略可能なデコレータの実装方法


Taken by Chris Gin under CC BY-NC

Pythonの中でも、僕が気に入っている文法がデコレータです。関数やメソッド、クラスの前に置くことで、様々な処理を行うことができます。デコレータを実装するには、ただ関数を書けばいいだけです。実際にコードを書く際にも良く使いますし、このブログでもいくつか紹介してきました。

このエントリーでは、デコレータにまつわるTipsを一つだけお届けします。ちなみにトップ画像の鳥ですが、デコレータ→仮面→masked birdと連想ゲームでした。仮面をかぶったように見える鳥みたいです。

デコレータがいまいちな点

何がいまいちって、引数のカッコの有無で挙動がかなり違う点です。カッコが無い時は、次のようになります。

def deco(func):
    """引数の無いデコレータ"""
    @functools.wraps(func)
    def _decorator_body(arg):
        try:
            # 事前処理
            return func(arg)
        finally:
            # 事前処理
            pass
    return _decorator_body

@deco
def func(arg):
    print "引数無しデコレータ付きの関数です"

# こう解釈される
# func = deco(func)

次は引数有り版です。

def deco(darg):
    """引数ありのデコレータ"""
    def _internal_params(func): 
        @functools.wraps(func)
        def _decorator_body(arg):
            try:
                # 事前処理
                return func(arg)
            finally:
                # 事前処理
                pass
        return _decorator_body
    return _internal_params

@deco("デコレータの引数")
def func(arg):
    print "引数付きデコレータがついた関数です"

# こう解釈される
# func = deco(darg)(func)

ご覧になれば分かるように、引数の有無で階層の数からして違っています。そのため、引数がなかった場合でも、引数を受け取る可能性があるのであれば、デコレータを使用する時にカッコを常に付ける必要があります。

カッコが必要なのに、カッコを忘れたとすると、本来はユーザが定義した関数が入って欲しい所に、_internal_params関数が入ってしまいます。エラーメッセージがきちんと出るわけではなく、実行してみて初めて分かるという、ちょっと想像しにくいバグが発生を誘発しやすくなります。

カッコが省略できるデコレータ記法

続きを読む
posted by @shibukawa at 04:16 | Comment(262) | TrackBack(0) | Python はてなブックマーク - 引数のカッコが省略可能なデコレータの実装方法

2010年03月16日

oreilly2sphinx


taken by caribb under CC BY-NC-ND

動物本と言えばオライリー。オライリーと言えば動物本。良質な洋書を翻訳した本が多く(書き下ろしもあります)、品質は折り紙付きな出版社です。オライリーの本に接する人は大きく二つに分かれると思います:

  • 本を読む人
  • 洋書を翻訳する人

このブログで紹介するスクリプトは、後者の人で、尚かつ翻訳にSphinxを使うよ!というレアな人向けです。適当に作ってみたのですが、便利そうなので公開します。テストは手元にあったThe Art of CommunityErlang Programming の2冊で行っています。どっちも良い本です。

Sphinxを使ってオライリー本の翻訳をされる方はご利用ください。

使い方

使う時はまず、xdoc2txtを使って、PDFからテキストを抽出します。その後は次のスクリプトに解析させると、章ごとにchapter_01.rstみたいなファイルが作られます。1章の前はpreface.rst。あとはそれらをまとめるindex.rstもおまけで作られます。翻訳用に特化しているので、原文は既にコメントアウト済みで出力されます。なお、出力したテキストファイルは、input.txtにリネームして、スクリプトと同じフォルダに置いてください。手抜きなのでご勘弁を。

今後直すとしたら

一番やりたいのは、セクションタイトルをきちんと出力する部分ですね。今は階層情報がすっかり抜け落ちてしまうため、全部フラットになってしまいます。だれか、目次情報(階層付き)の抽出の仕方が分かる方、情報お願いします。タイトルが分かっていたら、今は無理矢理やっている、タイトル抽出部とかをシンプルにできるだろうしー。別ファイルで、セクションタイトルの階層構造をインデントで表現したファイルを作っておいて、それを読み込むとかでもいいかも。

スクリプトのポイント

まぁ、コメントも書いてないし、テストも書いてないぐらいの適当スクリプト(でもそれでも動いてしまうPythonの恐ろしさよ)ですが、工夫したのは@handleデコレータを作って、イベント駆動型にしたことですね。@handleを増やせば勝手に色々なフォーマットを追加できるだろうし。段落の先頭の行の抽出とか、タイトルの抽出は適当に行っているので、精度はいまいちかも。上記の二つの本を流した感じではうまくいっているようには見えましたけど。

続きを読む
posted by @shibukawa at 22:37 | Comment(22) | TrackBack(0) | Python はてなブックマーク - oreilly2sphinx

2010年02月28日

Sphinx紹介セッション@BPStudy #30

bpstudy

Sphinx紹介

BPStudy #30に登壇してきました。ネタはSphinxの紹介です。資料はこちらにあります。Slideshareに上げてみたけど、固定長フォントが崩れて、ソースコードがうまく表示されないという、チュートリアルのテキストとしては大問題な感じだったので、ドキュメントがアップできるようになったというGoogle Docsを利用しました。いいですね、これ。Slideshareみたいに、ビュー数とか、ソーシャル機能がないのはちょっと寂しいけどね。

結果としては、Sphinxの良さを伝えることができたかな、と思っています。すごく反応して拡張機能に手を染め始めた人もいるし、僕自身も、Sphinxを紹介する武器として、今回スライドを作ることができたので、今後はいろんなところで生かして行きたいとおもいます。

Sphinxの良さというのは、結果だけを見せられても、伝わりにくいな、というのが僕の実感。複数ファイルを含むmakeが成功して、目次がばっとできるとSphinxの良さが実感できる、というのはあると思う。逆に、目次を作ってみないことには、「Wikiっぽいね」で終わってしまう人が多いと思う。なので、資料でもtoctreeを協調した説明になっています。自習される方は、ぜひ複数ファイル作って、toctreeを使って見てください。後は、使い方として、コメントアウトを使えば翻訳にも便利ですよ、というのを紹介すれば良かったかな?

何点かTwitter上に質問とかご意見があったので返事をしておきます。他にも何かあればお気軽に @shibukawa 宛にどうぞ。

WerkzeugとSphinxの関係は?

作者が一緒、というのが一つ。両方とも、pocooの兄弟。Sphinxが使っているライブラリの、JinjaとPygmentsも同じく、です。なので、Sphinxが純粋に外部に依存しているのは、docutilsだけです。

話が逸れましたが、元はWerkzeug用の、内製ドキュメントツールとして開発され、それがツールとして整備され、Pythonの本家のドキュメントを作成できるように機能拡張されたのが、今のSphinxです。

Wikiと比較するのは違うのでは?

とちぎRuby会議02の時のスライドを流用した、という理由もありますが、やはり、Wikiを使ったことがある人はすごい多いので、聞く人の過去の記憶とヒモ付けながら説明する方がイメージが掴みやすいだろう、という理由です。

Wikiも、内製ドキュメント用の環境としては、一定のシェアを持っていると思うし。Tracとかに内蔵のWikiとかも含めれば。Sphinxも、ソースコードのライブラリのドキュメントとかに便利な機能がそろっているという点で、WikiとSphinxは機能やアーキテクチャは違えど、同じマーケット上で争うライバルと言えると思います。

Sphinx独自のディレクティブはどのぐらいある?

複数ドキュメントをつなぐようなディレクティブは基本、Sphinx独自だと思って間違いないかと思います。あとは、独自にPygmentsを利用しているコードハイライトかな?

  • toctree
  • function, methodなどの、クロスリファレンス系
  • index
  • code-block

こんな所かと。

Sphinx自身のドキュメントのindex.htmlのソースが見られない

Sphinxのドキュメントのindex.htmlは、reSTを変換したのではなく、Jinjaテンプレートから生成したHTMLです。本当のソースは、以下の所にあります。

Djangoテンプレートっぽいという感想を持つ方も多いですが、これがJinjaです。BPStudyの中でも紹介したけど、ドイツ、オーストリア周辺のグループが作ったプロダクトではあるけど、名前の由来は、Template→temple(神社)→Jinjaという、日本の神社のダジャレです。

タイマーのない(LTではない)発表は久しぶりだったのですが、1時間30分の持ち時間で、ストップウォッチで測定した結果、発表時間は1時間30分09秒。我ながら、なんという精度。LTで鍛えた結果ですね。

Rails vs Django

Asakusa.rbの松田明さんと、最近、インタビューとかに出まくっている(1件は僕も絡んでいるけど)岡野さんのパネルトークでした。結構いっぱい、メモ取りました。機能の違いで優劣を語るのは簡単だけど、「どういう意図があってこうなっているのか?」という所まで深く突っ込んで聞けたのは面白かったです。前半を短くして、後半長くしても良かったんじゃないかな?と思うぐらいw

平均的な能力で見るとドキュメント、後方互換性などを考慮したプロダクトが多いPythonの方が安心感はあるのかもしれないけど、たまに尖ったプロダクトが登場する具合でいうと、Rubyは爆発力ありますよね。mod_rackのnginxでもApacheでも動きます、とか。へぇー、と思いました。

ちなみに「Railsはテンプレート周りだけが20世紀っぽい」という話が出たので、栃木県民としては黙っていられず、「ERBは、文字列生成メソッドとして使うのが本来の使い方」「Railsは、良くできたERBのサンプル」という、咳さんの言葉を紹介しておきました。

懇親会

松田さんと色々お話ができて勉強になりました。僕もどちらかというと、Rubyよりも、それを作るCコードの方に興味があるので、Asakusa.rbとか面白そうだな、と思ってます。後は、Pythonな人がjsonが好きで、Rubyな人がYAML/HAMLが好きって逆じゃない?とか、そんな話とか。勉強本に載せたい一言とかも頂きました。

@nanimosaとも色々お話。Blender 2.5はマジおもしろそう。Head First オブジェクト指向 in Pythonとかできそうな勢いですよ。あるいはオブジェクト脳のつくり方 with Python。へぇ、へぇ。そういえば、@nanimosaはOSCでBlenderの話をするとのことだったけど、どうだったのかなぁ?スライド楽しみ。

いい勉強会でした

最初から最後まで、ずっと楽しかったです。開始前に行った、写真美術館も良かった。こういう場を大事にしたいよね。

この件について、mixiに日記書いたけど、足跡が今回はぜんぜん付きませんでした。うーん、最近mixiやってないのかな?プログラマ系の人達は。ブログに記事を書いても、はてブよりもTwitterの参照数の方が多かったりもするし、情報の流れ方が、この半年で大きく変わったのを感じます。

とはいえ、Twitterも過去の情報を見るのがめんどうだったり、あっという間に流れて話題がうつりかわったりするので、万能とも言えないけどね。人間が扱える情報量自体が増えない以上、流れるメッセージが増えれば、一つ一つの重みは小さくなる。このまま小さくなり続けるのかな?それともまた違う流れが来るのかな?メッセージの重みが軽くなるアンチテーゼとしては、Google Buzzはアリだと思う。現状ではTwitterのメッセージをそのまま流している人も多いので、そんな気はしないだろうな、と思うけど。やはり、Googleの検索が使える意義は思ったよりも大きいと思います。

posted by @shibukawa at 00:11 | Comment(275) | TrackBack(0) | Python はてなブックマーク - Sphinx紹介セッション@BPStudy #30

2009年12月01日

Pythonスイーツ部栃木(ひとり)第一回ミーティング

[pythonスイーツ部栃木]8010

なにやらPythonのすいーつ部が楽しそうな感じで羨ましかったので、先駆けて、本日「Pythonスイーツ部栃木支部(ひとり)」を結成して、第一回ミーティングを開催してきました。場所は8010(パレット)です。会社の同期の結婚式で知り合った人(同い年)がこちらで働いているとのことで、近くに用事(組合orz)があったついでに、足を伸ばしてこちらまで来てみました。うーむ。喫茶店と聞いていたけど、男一人で来ると負けっぽい感じが漂うおしゃれな場所ぢゃないか。

[pythonスイーツ部栃木]フルーツサンドと和風スパゲティ

ここで有名なのはフルーツサンドとのこと。ということで、フルーツサンドと本日のパスタのセットを頼んでみました。最初に出てきたフルーツサンドとパスタでかなりお腹一杯。パスタおいしい。久しぶりにおいしいパスタ。満足じゃ。え、パフェも付いてくるの?パフェは、季節のパフェが選べます、ということで、巨峰とか柿とか、珍しいかんじのもいろいろありましたが栗にしてみました。栗の実が結構ざくざく入っていて、贅沢な感じ。

[pythonスイーツ部栃木]栗のパフェ

ということで、思いがけずスイーツを2つも堪能してしまって、満足しきったところで、ノートパソコンを広げて執筆開始。Pythonはしてないけどw 一時間ほどお邪魔して書きまくっていたけど、いつもと違う場所のせいか、集中していい感じで筆が進みました。いいね、いいね。

[pythonスイーツ部栃木]コーヒー飲みながらEmacs

こんな感じで、このお店のクオリティが高すぎるので、今後もここで活動していこうと思いました。

posted by @shibukawa at 21:43 | Comment(105) | TrackBack(0) | Python はてなブックマーク - Pythonスイーツ部栃木(ひとり)第一回ミーティング

2009年11月10日

KindleでLT!?

KindleでLT!?

Kindle 買いました♪LT職人としては、やらなきゃダメでしょ!ということで早速トライ。PDFを変換する方法をためしてみたけど、これはダメでした。PDFも画像+テキストみたいな形になってしまうため、プレゼンっぽい感じでは使うことは出来ません。で、ネットをうろいろしていたら、裏技機能でピクチャビューアとして使用するという方法が紹介されてました。さっそくやってみたのが↑これ。800×600のサイズの画像にしたけど、電池残量表示とかがあるため、欠けてしまいました。PowerPointで画像として出力できるデフォルトサイズ(横720)だと、ちょっと周りにわくができるけどちょうどいい感じです。ただ、画像は回転させておいてくださいね。左に90°。これで、書画カメラでLTって絶対誰かやるよね!きっとやるよね!先を越されるのは悔しいので、まずは写真をブログに載せてみました。

今までの調査結果・感想

  • 文字がキレイ。電子ペーパーキレイ。画面書き換えは遅い。
  • 通信機内蔵で、いつでもどこでも購入可能。Google検索やWikipedia検索とかもできてしまう。お金かからない。
  • 英々辞書内蔵。
  • 日本語化すれば日本語が出る。しないと出ない。
  • PDFなどをAmazonが提供するサービスで変換して入れることが可能。
  • でも、PDFよりも.mobiファイルを入れる方がインデックスとか使えるので相性いいね。
  • Amazonの.azwと.mobiはほぼ一緒。
  • .mobiファイルは昔懐かしPalmのPDBベース。PDB解析ライブラリを使えば中が読める。
  • PDBは4000バイトぐらい(細かい数値は今手元にメモがないので)の固定長レコードで構成されるファイル。
  • .mobiの中にはHTMLが入れられる。
  • 長いHTMLはレコード長でぶつ切りされてレコードに格納される。
  • 画像ファイルはテキスト情報のレコード(1番から、ヘッダ内に書かれたレコード数分続いている)の後ろにくっついているらしい。

後は画像部分の解析あたりかな。Art of Communityのファイルを解析したら文字がちょっと化けちゃったので、それも調べないと。ここが分かったら、Sphinxで$ make kindle とやれば.mobiファイルができる、なんて楽しいことが実現できるかも知れない。というか技術的にはできるはず。Kindle楽しいよ〜。ってKindleで本読んでないけどw

posted by @shibukawa at 23:31 | Comment(381) | TrackBack(0) | Python はてなブックマーク - KindleでLT!?

2009年11月03日

1日〜1週間でOSSに貢献する方法

OSC2009lt

OSC 2009 Tokyo/FallのLTで発表してきました。ACアダプタを忘れて、Windows PCで発表する予定だったのを、バッテリー持ちの良いMacBookにスイッチ。また、当日はPloneのブースで山本烈さんにアダプタをお借りしました。「電源とRGBケーブルありますよ!」とmixiを見てダイレクトメッセージを送ってくれた清水川さんともども、感謝申し上げます。

なぜかトリだったのですが、トラブルがあってその前に。タイマーが無かったのでiPod Touchの時計を表示しながら話していましたが、省電力設定がONのままだったので、ちょくちょくロックがかかってしまったのは失敗でした。今度から気をつけよう。

今回は話す内容がほぼそのままスライドになっているので補足するところは少ないのですが、今回もコメントを追加しつつスライドを紹介していきます。Slideshareにもアップしています。

OSC2009lt

それでは前回までのあらすじです。

OSC2009lt

とちぎRuby会議02というイベントが1週間前にありました。

OSC2009lt

テーマは儲かるRubyで、会費が50円でした。

OSC2009lt

そこのLTでは、儲かるドキュメントとして発表してきました。

OSC2009lt

そこで紹介したのが、Sphinxというドキュメンテーションツールです。Wikiと似たような、シンプルなテキストマークアップで記述してドキュメントを作っていくツールです。Wikiとの細かい違い、アジャイルにおけるテストとドキュメントの待遇の差などについて話をしてきました。あとは、DHHよりもイケメンがPython界にはいるよとか言いたかったけど、時間ありませんでした。

OSC2009lt

ぜひともSphinx使ってください、とアピールしてきました。ちなみに、Sphinx情報は僕のブログが日本で一番情報が集まっていると思いますが「コンカツ女子 IT」でググるとトップに出ますので、探してみてください。

OSC2009lt

そして、Rubyistの人達に、Sphinxを使って幸せになるための呪文をお伝えしました。今回のネタも多少かぶりますが、ほぼオリジナルです。手抜きはしてません。さて、これからが本題です。

OSC2009lt

今年の2009年9月11日の出来事を紹介します。

続きを読む
posted by @shibukawa at 09:26 | Comment(124) | TrackBack(0) | Python はてなブックマーク - 1日〜1週間でOSSに貢献する方法

2009年10月11日

Quick Sequence Diagram Editorがステキすぎる

sdeditext

Quick Sequence Dialog Editorというツールを見たときに「これはすごいかも」と思って、いろいろ触ってみたり、仕事で使って見たり、ドキュメントの翻訳をしたりしました。テキストベースで書いた擬似コードからUMLのシーケンス図を出してくれるというツールです。誤解を恐れずに例えると、シーケンス図専用のDoxygenみたいな。感じです。

コードを打つたびにリアルタイムに更新されるGUIが秀逸で、結構面白いです。擬似コードを使うので、マウスで絵を描くようにはできず、ナビゲーションもないので、コーディングルールを覚えないと使えないという難点はありますが(なので翻訳をした)、ルールはそんなに複雑ではないし、結果がすぐに絵になるので楽しいです。

GUIベースのツールだけど、コンソールコマンドとしても動作し、疑似言語で書かれたソースコードを読み込ませると画像ファイルとして出力してくれる機能もあるので、これはやるしかない!と思ってSphinxの拡張機能を作ってみました。Sphinxの中に.. sequence-diagram::というディレクティブを書いて、Quick Sequence Diagram Editorの擬似コードを書くと、ビルド時に絵にしてくれます。Doxygen用の拡張機能をコピーしてちょこちょこ置き換えただけの手抜き実装ですが、ちゃんと動いて画像を出してくれます。トップのスクリーンショットがその結果になります。

拡張機能を使うにはリポジトリに置いてあるコードをダウンロードして、sdedit.pyをコピーして、conf.pyの拡張機能の所に追加すると、専用のディレクティブとオプションが使えるようになります。詳しくはこちらをご覧ください。

まぁ、Sphinxに組み込まないで、単独で使っても面白いので、ぜひ使って見てください。

posted by @shibukawa at 17:59 | Comment(134) | TrackBack(0) | Python はてなブックマーク - Quick Sequence Diagram Editorがステキすぎる

Sphinxの検索を日本語対応にする

宇都宮のスフィンクス

写真は内容とは関係なく、栃木県宇都宮市のスフィンクスです。闇夜にいきなり現れるとかなりコワイです。

Sphinxの検索機能の日本語対応をしてみました。リンク先にはパッチ済みのSphinxが置いてあります。Sphinxは検索関連に関しては、かなり英語にハードコードされていましたので。やったことは以下の通り。

  • 日本語対応のSplitterの作成
  • 設定オプションに検索言語切り替えを追加
  • stemmingアルゴリズム、 stop wordsも検索言語と連動して切り替わるように変更
  • Sphinx-devのメーリングリストに、機能拡張要望をメール

日本語対応のSplitterの作成

まずやってみたのはSplitterの作成。Sphinxでは欧米言語を想定しているので、re.compile(r'\w+(?u)')という正規表現で単語を区切っています。何をやっているかというと、空白文字での区切りなので、日本語文字だと分けられません。日本語や中国語や韓国語は単語の意味などを類推したりしながら、単語を区切る処理が必要になります。形態要素分析というカテゴリの自然言語アルゴリズムです。

Sphinxは、ソースのreStructuredTextからHTMLにビルドするときに、ドキュメントを解析して、インデックスを作成して、JavaScriptのソースファイルとして出力します。実行時にはJavaScriptを使って検索をかけます。全部ブラウザ上で実行しちゃうのでサーバは不要というカラクリです。そんなこともあるのでインデックスが巨大になるN-Gram方式は使えません。

単なるインデックス作成のためには品詞とかまでは知る必要がないので、分かち書きというレベルの処理で大丈夫です。今回利用してみたSplitterは以下の3種類。

  • TinySegmenterPython実装。自分でも移植したんだけどコードを置いてきてしまったのでnyama++さんの実装を利用させてもらいました。
  • Mecab。C言語で実装された形態要素解析エンジン。ローカルで動かすならOSSではたぶん今のところ最強。
  • Yahoo!のWeb API。性能はいいらしい。

どれも一長一短あって、TinySegmenterはpure pythonなのでSphinxにバンドルするには最適。ただし性能はやや落ちます。Mecabは性能は高いけどC言語のモジュール。10MBぐらいあるので、バンドルするには難ありだし、Windowsとかのことを考えるとコンパイル前提で配るのも困難。Yahoo!APIはネットワーク接続が必要なのと、アプリケーションIDをユーザごとに登録する必要があるので気軽に使うには難あり。あと、後から分かったけど、結構重いです。ということで、3つとも実装してオプションで切り替えるようにしました。デフォルトはTinySegmenterなので、何もしなくてもひとまず動き、いい結果が欲しければちょっと努力してください、という感じになりました。

検索言語切り替えオプションの追加

続きを読む
posted by @shibukawa at 09:44 | Comment(810) | TrackBack(1) | Python はてなブックマーク - Sphinxの検索を日本語対応にする

2009年09月21日

Pythonって何?という人のためのSphinxチュートリアル[2]

tornado

シリーズものの記事の第3弾です。さて、それではSphinxならではのディレクティブをいくつか使っていきます。また、それ以外にも、前回ので書き忘れたreSTなんかも補足していきます。トップ画像が代わり映えしなくて済みません。

  1. Pythonって何?という人のためのSphinxインストール入門
  2. Pythonって何?という人のためのSphinxチュートリアル

前回書き忘れていた分

画像の挿入

ものすごく簡単です。

.. image:: tornado.png

これだけ。ファイルは、相対パスで指定します。上記の書き方をすると、そのファイルがあるのと同じフォルダを探索します。絶対パス/tornado.pngと書くとどうなるかというと、ソースコードの置いてあるルートのフォルダを起点に探索します。実際のファイルシステムのルートフォルダは探索しにいきません。

また、ビルドすると、デフォルト設定では、_build/html/_images以下にコピーされます。同じファイル名のファイルが複数あるとどうなるか・・・実験してみました。同じtornado.pngを、いろんなフォルダに置いておいて実行してみると、tornado.png, tornado1.pngなど連番がふられて、上書きされたり、といった事故は起きないようになっています。良くできていますよね。

インラインマークアップ

ちょくちょく使うのが、インラインマークアップ。等幅にしたり、太字にしたり。

コード例:
**太字**, *イタリック*, ``等幅``

結果例:太字, イタリック, 等幅

注意点としては、前に書いたエントリーのリンクの説明と同様に、日本語混じりの文章の中に書く場合は、**太字** の前後にスペース、もしくは(),などの区切り文字がなければ識別されません。挟まっている文字列の前後にはスペースは不要です。アンダースコアをスペースと見なすと、_**太字にしたい文字**_といった感じにする必要があります。もしくは、\+スペースにすると、出力結果にスペースが入らないで、インラインマークアップを識別させることができます。日本語は単語区切りの言語ではないので、\+スペース(\_**太字にしたい文字**\_という表記をよく使うことになると思います。

リスト

他のテキストベースのマークアップとほぼ一緒です。

* Tornado(nginx; 4 frontend)
* Tornado(1 single threaded frontend)
* Django(Apache/mod_wsgi)

アスタリスクの代わりに、1. 2. 3. と書けば数値が前に付くリストも作成できますし、インデントして、その中にリストを書けば、複数階層のリストも書くことができます。ただし、階層が変わるところでは、前後に空行を1行いれる必要があります。

テーブル

テーブル(表)も作成できます。昔は日本語の扱いがおかしかったらしいのですが、今では問題なく扱えます。Tornadoでは使っていないので他所からサンプルをコピーしています。見出しセルの指定、セルの結合(横方向、縦方向)ができます。

+-------------+----------------------+---------+---------+------+
| Feature List                       | Python2 | Python3 | Ruby |
+=============+======================+=========+=========+======+
| Push API    | following_function   | O       | O       |      |
+             +----------------------+---------+---------+------+
|             | following            | O       | O       | O    |
+-------------+----------------------+---------+---------+------+
| Pull API    | Queue                | O       | O       | _    |
+-------------+----------------------+---------+---------+------+

こちらが簡易表記です。縦方向のセルの結合はできません。これから説明していく、索引のまとめの表を作ってみました。後でもどってきて確認してみてください。

======= ==== ==============
入力         出力
------------ --------------
種類    引数 索引
======= ==== ==============
single: A; B A -> B
single: A    A
pair:   A; B A -> B, B -> A
======= ==== ==============

ブロックのディレクティブ

それでは、Tornadoの翻訳で使ったやつを中心に、Sphinxのディレクティブを説明していきます。

続きを読む
posted by @shibukawa at 19:40 | Comment(1722) | TrackBack(1) | Python はてなブックマーク - Pythonって何?という人のためのSphinxチュートリアル[2]

2009年09月13日

Sphinxでライブラリリファレンスを書くための新機能?

http://pythonic.pocoo.org/2009/9/12/new-in-sphinx-1-0-domains

Sphinxの開発者のGeorg Brandl氏が今日MLに投稿して明らかになった、新機能案。Sphinxはふつーの文書というよりは、ライブラリのリファレンスを書いたりする機能が充実していて、そちらで使われることを想定して開発されている(Pythonの標準ドキュメントで使われている)のですが、そこに大きく手が加わるかも、とのことです。今までは、関数の説明を書く時は、

.. function:: following(identifier)

   関数の説明

とやっていたのですが、py:functionなど、言語指定ができるようになるみたいです。今まではPythonの場合はfunction、C言語の場合はcfunctionみたいにそれぞれ別のディレクティブだったんですが、他の言語からも使われることを想定しての機能拡張みたいです。berryMQみたいに、いろんな言語のAPIを揃えようとしている場合にもうれしい変更です。はたして、rb:functionは追加されるのか?

ますます用途が広がっていきそうです。

posted by @shibukawa at 12:12 | Comment(225) | TrackBack(0) | Python はてなブックマーク - Sphinxでライブラリリファレンスを書くための新機能?

Pythonって何?という人のためのSphinxチュートリアル

tornado

前回、インストールのエントリーを書きましたが、Tornadeドキュメントの翻訳を例に、実際にSphinxでの作業の流れをお見せしたいと思います。

まずはワークフォルダを作る

作業をするには、ファイルを置く場所が必要です。ソースコード、設定ファイル、ビルド後の成果物などなど、いろいろ必要になります。そこでフォルダを作成する必要があります。僕の場合は翻訳とかの作業は(ホーム)/work/(作業フォルダ)という場所で行うことが多いので、その前提で話しをすすめます。Tornadoの翻訳の場合はチームで作業をしたので、bitbucketを使って共有環境を用意しましたのでその説明も一緒に。

共有をする場合はMercurialをインストールしてください。Windowsの場合はTortoiseHgが便利です。MacとUbuntu Linuxの場合は以下のようにします。

# Mac OS Xの場合
$ sudo port install mercurial
# Ubuntu Linuxの場合
$ sudo apt-get install mercurial

TortiseHgはUbuntuでも使えるそうな。試してませんが。

Mercurialのついての詳しい説明はしませんが、「入門Mercurial 」という藤原さんのすばらしい本があるのでオススメしておきます。

一人作業用

ただフォルダを作るだけですので、Windowsならエクスプローラで「新規フォルダ」で作ってもいいのですが、今後の作業はコマンドライン上で行うので、ぜひともコマンドラインで。

> mkdir ~/work/tornado_docjp
> cd tornado_docjp

一人作業の場合でも、できたフォルダの中で$ hg initとするか、TortoiseHgの場合には右クリックで"Create Repository Here"をすると、リポジトリができます。Mercurialを使ってバージョン管理できて、過去の履歴が見えたり、差分がみれたりするので、一人作業の場合でもMercurialをおすすめします。

Bitbucket.orgを使って複数人作業する用

僕はリポジトリとしてはBitbucket.orgを使用しています。Bitbucketにはいろいろなプランがありますが、おおまかにまとめると、以下のような特徴があります。

  • リポジトリ、IssueTracker(高機能なTodoリストみたいな機能、Wikiが使える
  • 公開リポジトリはいくらでも作れる
  • 無料でもプライベートなリポジトリが1つ使用できる
  • SSHでの接続ができる
  • 150MBまで無料
  • Gitよりもコマンドが覚えやすい、Mercurialが使える
  • 有料プランになれば、自分のドメインの中で動いているようにCNAMEの設定ができる

新規でユーザ登録をする場合は上段にある Plans & Signup をクリックして登録をしてください。ユーザ登録、ログインまでは終わっていると想定して話しを続けます。

上段のRepositoriesをマウスオーバーすると、プルダウンメニューがでてきますので、すぐ下の Create New を選択します。後は枠を適当に埋めてCreate repositoryを押せば完了です。あとは、作業フォルダの上のディレクトリ(今回の場合は~/work)に移動して、Webサイトに載っている通りにMercurialを実行すれば完了です。

$ hg clone https://shibu@bitbucket.org/shibu/tornado_docjp/

TortiseHgを使う場合は右クリックから「clone」を選び、clone元として、https://shibu@bitbucket.org/shibu/tornado_docjp/を入力して実行します。

bitbucket

Sphinxのプロジェクトを作成

前置きが長くなりましたが、Sphinxの作業に入っていきます。

続きを読む
posted by @shibukawa at 11:22 | Comment(344) | TrackBack(2) | Python はてなブックマーク - Pythonって何?という人のためのSphinxチュートリアル

2009年09月12日

Tornadoウェブフレームワーク日本語訳ができるまで

tornado

Facebookが新しいウェブのフレームワークを公開しました。このフレームワークはすごいですよ。最初から、最近よく使われるようになったOpenIDなどの外部認証に対応しているし、セッションをたくさん張るようなウェブアプリにも対応しているし、 nginxをフロントに立てるのを前提としています。それでいて、ソースコードは少なく、サイズはとても小さい。極めてモダンで無駄のないウェブアプリケーションサーバです。もちろん、Google AppEngine/Pythonでも使えます。Rails/Djangoなどの拡大路線に対抗して、最近は小さいフレームワークもまたいくつか出てきましたけど、小さいからといって我慢しなくてはいけないこともないし(今までの資産が生かせないぐらい?)、こいつはRails/Djangoの対抗馬として急浮上する可能性も大ですね。

そんでもって、日本語訳を公開しました。オリジナルの文書に準拠してCC3.0での公開です。

何せ、日本のニュースサイトに上がったのは昨日の午後。@voluntasも書いていますが、24時間たたないうちに翻訳が完了するという、文字通り「竜巻のような」勢いで翻訳しました。翻訳の顛末を時系列に列挙します。

続きを読む
posted by @shibukawa at 11:44 | Comment(276) | TrackBack(0) | Python はてなブックマーク - Tornadoウェブフレームワーク日本語訳ができるまで

2009年09月11日

Pythonって何?という人のためのSphinxインストール入門

sphinx

この前のブログのエントリーにも書きましたが、Sphinxというステキすぎるツールがあります。ドキュメントがどんどん書きたくなっちゃうステキなツールです。ですが、残念ながら、使用するためにはインストールする必要があります。Pythonって何?という人には少々敷居が高いため、解説の記事を書いてみました。

[STEP 1] Pythonからインストールする場合

WindowsではPythonからインストールする必要があります。一発でインストールできる環境を持っている人は最後の方のインストール法に飛んでください。また、Mac OS Xみたいに、最初からPythonから入っている人は[STEP 1]は飛ばしてください。

Windwsの場合

http://python.orgを開きます。Pythonの総本山です。恐れないで行きましょう!左側のサイドバーから、Quick Links(2.6.2)の中のWindows Installerをクリックしてダウンロードして、インストールします。

installpython

後は通常、良くあるようなインストーラが起動しますので、そのままインストールしてください。

installpython

初期設定のままインストールすると、C:\Python26\以下にインストールされます。環境変数の設定を開き、C:\Python26;C:\Python26\Scriptsを追加してください。追加したくない場合には、各コマンドの実行例のコードサンプルの場合は、python.exeとあれば、C:\Python26\python.exe などと、適宜読み替えてください。

「名前を指定して実行」でcmdと入力するか、コマンドプロンプトを起動して、pythonと入力したら、 >>> で何か入力させる画面が出ます。これはインタラクティブモードと呼びますが、これが表示されていればインストールは大丈夫です。CTRL+Zで抜けてください。

[STEP2]easy-installをインストール

続きを読む
posted by @shibukawa at 00:52 | Comment(174) | TrackBack(4) | Python はてなブックマーク - Pythonって何?という人のためのSphinxインストール入門
検索ボックス

Twitter

www.flickr.com
This is a Flickr badge showing public photos and videos from shibukawa.yoshiki. Make your own badge here.
<< 2016年12月 >>
        1 2 3
4 5 6 7 8 9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29 30 31
最近の記事
カテゴリ
過去ログ
Powered by さくらのブログ