2009年09月13日

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の作業に入っていきます。

Sphinxでプロジェクトを作成するには、以下のようにタイプします。

> sphinx-quickstart

いくつか質問されます。必要なのはプロジェクト名、バージョン番号、著者の名前です。今回はTornadoのドキュメントの翻訳なので、プロジェクト名は"Tornado"、バージョン番号はTornadoにあわせて"0.1"、著者名は"Facebook(Translated by SHIBUKAWA Yoshiki)"を入れました。途中でextensions(拡張機能)を組み込むか、という質問が多いのですが、数式を使う、Pythonのソースコードと連携する、ToDoリストを使うということがなければ不要ですので、もったいないとおもってyをおさなくても大丈夫ですよ。

共同作業をしている場合には、ここでできたファイル群をMercurialに登録しておきます。以下のコマンドを使用して追加していきます。ワイルドカードも使えますし、ディレクトリ名を指定すれば子供のファイルも全部登録してくれます。TortoiseHgの場合右クリックのメニューから登録していきます。

$ hg add ファイル名

登録ができたら、$ hg commitをしてローカルのロポジトリに変更を登録します。comiitしたら、$ hg pushとすると、Bitbucketのサイトにアップロードされます。ちあみに、他の人がpushした内容を取り込みたい場合には、$ hg pullしてから$ hg updateすることで反映されます。Mercurialは分散リポジトリということで、他の人の変更部分だけを直接もらってきて反映したり、ということもできますが、その当たりは長くなるので書籍なりを参照してください。

ソースのファイルを作成する

オリジナルのドキュメントは、1ファイルのHTMLになっていますが、あまりに大きくても表示が大変だったり、まちがってスクロールしてしまったときに迷子になってしまったり、そもそも複数人での作業が面倒なったりということもありますし、セクション単位で分けると、逆に細かすぎてページ間の移動が面倒ですので、適度なページに分割するのをオススメします。今回は独立性の高い以下の4ページに分割することにしました。

ファイルを分割を決めたら、上記の名前のファイルを作成して、index.rstの目次作成のディレクティブ(toctree)に作成したファイル名(拡張子なし)を列挙します。

.. toctree::
   :maxdepth: 2

   start
   module_index
   walkthrough
   deploy

追加したら、またファイルの追加(hg add)をしてコミット(hg commit)しておきます。今回はindex.rstも編集したので、コミットの際にindex.rstの名前も出てきます。

テーマの色を変える

次に、テーマの色をカスタマイズしてみます。最後にやってもいいのですが、雰囲気が出て、やる気がでます。まずはビルドしてみます。

> make html

これでhtmlファイルができますので、ブラウザで開いてこれを見ながら編集してみましょう。開いたら、conf.pyを開いて編集します。html_theme_optionsという項目があるので、ここで色を変更します。設定できる項目はこちらを参照してください。Tornadoのドキュメントの設定ファイルの場合は以下のようになりました。Pythonに慣れない方は難しいと思いますが、設定値、キーの両方をシングルクオート(')、もしくはダブルクオート(")のどちらかでくくります。設定値とキーの区切りはコロン(:)、設定の組の境目はカンマ(,)を使用します。特にカンマのうち忘れは何度か失敗すると思いますのでご注意を。

html_theme_options = {
  'relbarbgcolor':'#4682B4',
  'sidebarbgcolor':'#C0E6F0',
  'sidebartextcolor':'#367294',
  'sidebarlinkcolor':'#3A2BC2',
  'headbgcolor':'#E6E6FA',
  'headtextcolor':'#4662A4',
}

最終的にTornadoっぽい色になりました。編集したら、Mercurialを使っている場合にはまたコミット、プッシュします。ちょくちょくコミットすると、失敗しても巻き戻したり、過去の記録が見れたりするので、便利です。

ドキュメントを書く

それではこれからSphinxが使用している、reStructuredTextでドキュメントを作成していきます。詳しくはreStructuredText入門をご覧ください。その中でも頻繁に使われると思うものを紹介します。Sphinxを使っているサイトは、reSTのソースコードがみられるようになっていることが多いので、気になる箇所はソースコードを参照するといいでしょう。ちなみに、文字コードをUTF-8にしてファイルを作成すると、デフォルトの設定のままでも日本語が普通に出ます。入力したら、make htmlでビルドして、ブラウザで見たり、FTPでウェブサイトにアップロードしたりしてみてください。また、共同作業している場合にはコミット作業を忘れずに。

タイトル

タイトルは、=, -, ~などの記号を使って、タイトルの文字列の上下、もしくは下の行に装飾することでタイトルになります。例えば上下を装飾したタイトルの次に、下だけ装飾したタイトル、使う文字の変更など、種類を変えていくと、大見出し、中見出し、小見出しといった感じで、reSTの方で取り扱ってくれます。ちなみにソースファイル間でタイトルで使う記号や書き方は統一しなくてもかまいません。ファイルの中の大見出しとその次の中見出しまでは、トップページの目次に表示されるようになります。僕の場合は以下のように書くことが多いです。

============
タイトルです
============

サブタイトル
============

さらに小さく
------------

それでも足りない場合
~~~~~~~~~~~~~~~~~~~~

段落

空行を空けると、段落になります。ちなみに、タイトルなどの他の要素との間も必ず空行を空けるようにします。

tornado.web パッケージの詳細のウォークスルーについては、後半の章に
書いてあります。

私たちは、モジュール間の相互依存性を減らそうと、コードベースをきれい
にしようとしています。理論的には、パッケージ全体を使用するのではなく、
必要なモジュールを個別に使用できるようにすべきです。

リンク

HTMLではリンクは必須ですよね。外のURLへのリンクは`表示する名前 <URL>`_ ように記述します。最後のアンダースコアは忘れないように。また、文書中に埋め込む場合には前後にスペース、もしくは\+スペース(空白が入ると困る場合)を挟みます。ダウンロードファイルへのリンクは以下のように書きます。

`tornado-0.1.tar.gz <http://www.tornadoweb.org/static/tornado-0.1.tar.gz>`_

コメントアウト

翻訳をしていると重要になるのがコメントアウトです。原文を消してしまうと訳の見直しがしにくくなります。かつては自分でテキスト処理のプログラムを作って削除とかしてましたが、reSTでは最初からこの機能があります。最近はこれのためにSphinxを使っているといっても過言ではないぐらいです。ピリオド2つ+スペースで始めます。そうすると、次にピリオドが始まったインデントに戻るまでの区間がコメントアウトされます。

.. We attempted to clean up the code base to reduce interdependencies 
   between modules, so you should (theoretically) be able to use any of 
   the modules independently in your project without using the whole package.

私たちは、モジュール間の相互依存性を減らそうと、コードベースをきれいに
しようとしています。理論的には、パッケージ全体を使用するのではなく、
必要なモジュールを個別に使用できるようにすべきです。

サンプルコードを書く

サンプルコードを書く場合には、ディレクティブというものを使用します。コメントも一種のディレクティブなので、「同じインデントに戻ってくるまでが」というルールは一緒です。コロン二つの後ろにハイライトのルールをどの言語にあわせるか、というのを記述します。使える言語やフォーマットはここを参照してください。この翻訳で使用したのは、bash(コマンドライン用)、python、html、nginx(nginxというサーバの設定ファイル)などです。

.. code-block:: bash

  tar xvzf tornado-0.1.tar.gz
  cd tornado-0.1
  python setup.py build
  sudo python setup.py install

さて、長くなってきたので、このあたりでいったん区切りたいと思います。ファイル内の装飾などに関してはreStructuredText入門にいくつか紹介していないネタがあります。また、文書間のリンクなどについては、Sphinxの固有のディレクティブを使うことでできるようになります。Sphinxについては、まだ書きたいネタがいくつかあるので、またちょくちょく書く予定です。

posted by @shibukawa at 11:22 | Comment(344) | TrackBack(2) | Python はてなブックマーク - Pythonって何?という人のためのSphinxチュートリアル
この記事へのトラックバックURL
http://blog.sakura.ne.jp/tb/32098239
※ブログオーナーが承認したトラックバックのみ表示されます。

この記事へのトラックバック

Pythonって何?という人のためのSphinxチュートリアル[2]
Excerpt: さて、それではSphinxならではのディレクティブをいくつか使っていきます。また、それ以外にも、前回ので書き忘れたreSTなんかも補足していきます。
Weblog: 渋日記
Tracked: 2009-09-21 19:40

とちぎRuby会議02 - その1(LT)
Excerpt: とちぎRuby会議02がありました!普段は技術や「普及するには?」ということについて語られることが多いIT系イベントですが、仕事としてのマインドについて多くのメッセージを聞くことができました。今回..
Weblog: 渋日記
Tracked: 2009-10-25 11:36
検索ボックス

Twitter

www.flickr.com
This is a Flickr badge showing public photos and videos from shibukawa.yoshiki. Make your own badge here.
<< 2016年08月 >>
  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 さくらのブログ