Sphinxのディレクティブで、special admonitionを使ってみる

Sphinx 1.1のドキュメントサイトを見ていたら、reStructuredText入門のページに淡い背景色がある"See also"という囲み文章がありました。これはどうやって書いているのだろうと、ソースを表示してみたら表示とディレクティブが同じでした。

.. seealso::
文章

真似してローカルのSphinxドキュメントに seealsoを追記してみたら、こんな表示になりました。
20110614seealso

私が使っているHTMLテーマ「haiku」では、背景色が淡いグリーンになりました。そして、seealsoは日本語で「参考」と表示されています。このディレクティブは、忠告としてまとめられている admonitionの一つで他にもいくつかあります。どんな表示になるか興味があったので試してみました。

まずは、attention。枠がうっすらと見えるだけで色は付いていません。
20110614attention

cautionは「ご用心」、dangerは「危険」、errorは「エラー」、importantは「重要」で、表示はattentionと同様でした。tipも表示は同じですが、「ちなみに」と訳されていました。「tip」と「ちなみに」の意味合いは、少し違うような気もします。

続いて、noteを使ってみるとアイコン?が表示されました。
20110614note

warningは、背景が淡い黄色になって画像も付いています。
20110614warning

ほとんどのテーマが note、warningにだけスタイルを適用すると書かれている中、haikuテーマは seealsoにも適用されることが分かりました。dangerやcautionの見た目が予想外におとなしい点は少し残念ですが、noteやwarningは目立たせたいところに使うと良いかもしれません。

| | コメント (0) | トラックバック (0)

Sphinx、ビルド設定ファイルでHTML出力の見た目を変える

私が Sphinxを使っているのは、テキストファイルを書いて、コマンドプロンプトで make html を実行すれば簡単にHTMLファイルを生成できるからです。例えばウェブサイトを更新したい時に、変更箇所がほんの少しなら HTMLのタグを直接書くこともあります。しかし、Sphinxのように、タグやCSSを意識せずにテキストエディタで文章を書いていけば良いというのはとても楽ですし、書きたい文章以外のことを考えなくてすみます。使いこなすと CSSも設定できますが、知らなくても予め用意されたテーマを使うことで見た目の整ったドキュメントを作成できます。

今日は、ビルド設定ファイルと呼ばれる conf.py でオプションを設定することで、生成されるHTMLファイルの見た目を少し変えてみました。詳しいオプションの解説は "Sphinx 1.1 Documentation" HTML出力のオプションをご覧ください。

[注] この記事ではWindows環境で使っているため、「フォルダ」という語を使いますが、他の環境を使用している方は「ディレクトリ」と表現されることもあります。

conf.py は、Sphinxのプロジェクト名で作成したフォルダの中に出来る sourceフォルダに入っています。.rst ファイルと同じようにテキストエディタで開いて編集できます。開いてみるとシャープ記号(#)で始まる行がほとんどで、じっと見るとちらほらと表示に関係しそうな文字が混じっています。

最初に何やら説明のような文章があり、"General configuration"の部分を過ぎると "Options for HTML output"が見つかります。ここからがHTML出力のオプションですが、シャープ記号(#)で始まっている行は、ビルド(make htmlを実行すること)では無視されます。設定したいオプションは、必ず行頭のシャープ記号を削除して、イコール記号(=)の後ろにその内容を入力してください。

まず、初期段階でHTMLを生成した際の表示です。
201106011_2

テーマを設定してみました。ShinxではHTMLのテンプレートファイルが「テーマ」として予め用意されています。その中から「haiku」を選びました。

html_theme = 'haiku'

結果はこちら。見た目がガラっと変わりましたね。
201106012

次に、haikuテーマでページの一番上に表示されるタイトル(上の画像で「support-service v0.1 documentation」となっているところ)を変更し、ロゴ画像を入れてみます。

html_title = 'Product Support Guide'
html_logo = 'ロゴ画像のファイル名をパスで指定'

結果はこうなりました。
201106013

最後に、また別のテーマ「traditional」での表示を見てから終わりにします。
201106014

| | コメント (0) | トラックバック (0)

Sphinxでページ内リンク(ページ内の目次)を作る

随分前にSphinxの記事を書きましたが、しばらく使っていなかったのでディレクティブの書き方を忘れていました。先週、社内で使う文書を作ろうと思って、再び quick-start から始めたので少し思い出しました。今日は、HTMLではページ内リンクとして捉えていたものを使ってみた結果を記事にします。

Sphinxでは toctreeを書けば、各パラグラフへのリンクは自動で生成されます。目次のリンクをクリックすると、そのページの段落始まりまでジャンプします。しかし、あるページの内容が多い時(ページが長くなってしまった時)は上部に目次を置いて、ページ内でジャンプさせたいと思うこともあります。そういえばページ内で目次を作れたはずだと思い出し、Sphinx 1.1 documentationの「ディレクティブ」を探したところ、「contents (現在のファイル内だけの目次)」を見つけて、英語の解説ページを開きました。

目次を入れたいページの画像です。
reStructuredText Directives "Table of Contents"

201105301

赤丸を付けた小題だけを目次にしたいと思い、ひとまず一行だけ追加して make html しました。

.. contents::

結果はこちら。
201105302

やりたいことが三つ。

  1. 一番上にある大きなタイトルは目次には不要なので削除したい
  2. 「Contents」を「目次」に変える
  3. 小題のサブにあたる「手順」は表示されなくて良い

contentsの解説をじっと読んでみると、オプションに toctreeと同じ depthがあります。これを指定することで、「手順」の非表示はできそうです。大きなタイトルを省くには、local というオプションが使えそうです。「目次」を表示させるには、Table of Contentsの名称を設定すれば良いようです。試してみましょう。

.. contents:: 目次
   :local:
   :depth: 1

結果はこちら。
201105303_2

使ったオプションの解説を一部書いておきます。
depth: 目次に表示したいセクションのレベルを整数で指定する。数字がない場合は、指定なし。
local: 空で良い。ディレクティブで書かれたサブセクションのみを目次として表示する。

次回からページ内の目次はすいすい書けそうです。

| | コメント (0) | トラックバック (0)

Sphinx、セクションのヘッダを比べてみる

Sphinxでは文字列にアンダーラインを付けて、見出しや小題を作ります。見出しにしたい文字列の次行に、アスタリスクやイコール、ハイフンで下線を書いて makeすると、太字や他の文字列と異なる色で表示されます。記号によってどのような見出しになるのか試してみました。

ソースコード

===============
Section Title
===============

表示確認、上下二重線

---------------
Section Title
---------------

表示確認、上下破線


Section Title
=============

表示確認、下のみ二重線

Section Title
-------------

表示確認、下のみ破線

Section Title
`````````````

表示確認、下のみシングルクォート

Section Title
'''''''''''''

表示確認、下のみカンマ

Section Title
...............

表示確認、下のみピリオド

Section Title
~~~~~~~~~~~~~

表示確認、下のみチルダ(波の形)

Section Title
*************

表示確認、下のみアスタリスク


Section Title
+++++++++++++

表示確認、下のみプラス


Section Title
^^^^^^^^^^^^^

表示確認、下のみサーカムフレックス(山の形)

上記のソースコードを makeした結果が次の画像です。

,p20110210

201102102

Sphinxdoc と haiku の二種類のテーマで見てみましたが、どちらも途中から表示サイズや色、太さが変わらなくなりました。(7番目に使った記号から変化がなくなる) 日本語のreStructuredText入門 「セクション」を読むと、次の記述がありましたので、これは出力形式であるHTMLの制限だと思われます。

- 引用 -
「ただし、ほとんどの対象となる出力フォーマット(HTML, LaTeX)は、ネストできる深さには限界が設定されている、ということは忘れないでください。」

上下に記号を使ったものと、下のみに使ったものは異なるレベルの見出しと認識されますが、上下の記号の種類と長さ(桁数)が揃っていなければなりません。英語の解説を読むと、特に見出しに適した記号があると書かれていました。

= - ` : . ' " ~ ^ _ * + #

記号を使って見出しを作ると、自動でこの見出しへのハイパーリンクが生成され、"reference name"と呼ばれるハイパーリンクのターゲットはセクションタイトルと同じになります。

| | コメント (0) | トラックバック (0)

Sphinx、image(画像を挿入するディレクティブ)

しばらくSphinxで文書作成を続けているので、使ったディレクティブ(ピリオド二つで始まる決まった書き方)と、その時の失敗を書いてみます。make結果が思ったような表示にならない原因は、ディレクティブの仕様が書かれている英語サイトをじっくり読まなかったからです。新しいディレクティブを使う時は example のソースコードをコピー&ペーストして make結果を見てみるのが良いかもしれません。

reStructuredText Directives

このページの最初を見ると、ディレクティブのsyntax(構文)が書いてあります。ピリオド二つとスペースで始めて、ディレクティブタイプ(image や contentsなど)を書き、二つのコロン(::)を付けます。後ろには arguments と呼ばれる、そのディレクティブを使う際、必ず書くものと、optionsと呼ばれる追加できる情報を書きます。
例えば、画像を挿入するディレクティブの imageには、画像ファイルのパス(置き場所)が必須です。HTMLで imgタグを使う時に srcが必須なのと同じです。imageのオプションとして、alt(代替テキスト)や width(幅)、height(高さ)、scale(縮小率)などがあります。

Image Directive
日本語の説明部分には scaleの記述はありません。
reStructuredText入門 「画像」

image ディレクティブを使い、元の画像のサイズを変えて表示できることを知った時、私は英語ページの詳細をきちんと読んでおらず、幅と高さ(width、height)に加えて、縮小率(scale)も書いていました。しかし、make結果では想像よりもかなり小さく表示され、どこかがおかしいとよく読んでみました。すると、幅もしくは高さを書けば指定サイズで表示され、scaleも書くと統合される(width または heightに scaleを掛けた割合)ことが分かりました。次のソースコードを makeすると、表示される画像の幅は 100pxになります。

.. image:: images/astah-screenshot.png
   :width: 200px
   :scale: 50%

画像を挿入するディレクティブには他に figure がありますので、次はそちらも使ってみたいと思います。

| | コメント (0) | トラックバック (0)

Sphinx、csv-tableを使ってテーブル(表)を作る

1月28日に、Sphinxのシンプルテーブルを使って表を作る際、日本語のソースでは罫線の長さと make結果の見た目に違いが出るため、調整が必要なことを書きました。
Sphinxでテーブル(表)を作成する時の注意点

罫線(===)で作成するシンプルテーブルは簡単ですが、行数や列数が増えると見た目の調整に手間取ったり、長い文言を使用した時にテキストエディタでスクロールが必要になって面倒だったりします。もっと作り易い方法があるのでは?と思って、Google検索したら、tipsを書いている方が居ました。

2011/1/27 「文章を書く際のtips」 (そこはかとなく書くよ。)

このブログを読んだ後、以前作成していたテーブルを  csv-tableで書きなおしてみました。

.. csv-table:: 
   :header: "図の名称", "参照", "作成", "編集", "削除"
   :widths: 30, 10, 10, 10, 10

   "クラス図", "OK", "OK", "OK", "OK"
   "コミュニケーション図", "-", "-", "-", "-"
   "データフロー図(DFD)", "-", "-", "-", "-"

make結果のHTML(FireFox 3.6.13で表示)
ハイフンは空欄で処理されていますね。
Csvtable1

IEで表示すると、シンプルテーブルと同じく縦線が表示されませんでした。
Csvtable2

csv-tableのオプションにある "width"(各列の幅をピクセルの数値で指定する)を書かない場合、等幅のテーブルができました。
Csvtable3

csv-tableの説明ページを見ると、このディレクティブ(ピリオド二つで始まる決まった書き方)のオプションである file、url にはセキュリティホールがあるそうです。私は今のところ使わないようにしておきます。

カンマで区切るだけで make後の表示を見て幅調整する必要がないため、次回のテーブル(表)は csv-table を使ってみたいと思います。

| | コメント (0) | トラックバック (0)

Sphinxでテーブル(表)を作成する時の注意点

ドキュメント作成ツール Sphinxについて初めてブログに投稿してから3ケ月以上経ってしまいましたが、地道に文書作成に使っています。makeではHTMLを作っているだけですが、組込みのHTMLテーマを利用することでいくつか見た目の印象が異なる文書を作成できて便利です。練習は別として初めてまとまったドキュメント作成に使ったのが「sphinxdoc」という薄い青灰色のテーマで、他に「traditional」と「nature」の見た目を確認し、今作っているものは「haiku」を選んでみました。

さて、昨日もSphixを使って少しドキュメントを書いていたのですが、罫線を利用してテーブル(日本語だと「表」がいちばんイメージしやすい)を作成すると、かなり調整が必要と分かりました。サンプルとして、rstソースのテキストとFireFox 3.6.13で表示したHTMLの画像を載せておきます。

reStructuredText入門  「テーブル」

テーブル作成での罫線の長さ

====================  =======  =======  =======  =======
図の名称               参照     作成     編集     削除
====================  =======  =======  =======  =======
クラス図               OK       OK       OK       OK
コミュニケーション図   -        -        -        -
データフロー図(DFD)    OK       -        -        -
====================  =======  =======  =======  =======

rstのソースでは日本語と線がずれている(線より日本語が長い)ところはありません。しかし、make結果のHTMLを見ると、等幅フォントのソースでは文字数が多いコミュニケーション図よりも、データフロー図(DFD)の方が長く見えますし、見出し行の「削除」は幅が不足して縦に表示されています。

Table1_2

そこで、ソースに戻って「図の名称」列の罫線を半角2桁増やしてみました。すると、今度は「作成」が縦に表示されました。
Table2

「図の名称」列の罫線を、さらに半角2桁増やしてみます。

========================  =======  =======  =======  =======
図の名称                   参照     作成     編集     削除
========================  =======  =======  =======  =======
クラス図                   OK       OK       OK       OK
コミュニケーション図       -        -        -        -
データフロー図(DFD)        OK       -        -        -
========================  =======  =======  =======  =======

Table3
ようやくすっきりと表示されました。

プロポーショナルフォントで表示されるため、ソースとHTMLの見え方が異なっていますし、どうもテーブルの左側で罫線が不足していると認識されると、右側の表示に影響が出るようです。また、FireFoxの例をあげましたが、同じmake結果のHTMLを IE8で表示すると、縦の線が見えません。rstのシンプルテーブル(==で表を書く方法)を使った場合、IEでは縦線が表示されないのです。
Table4

表示を確認しながら、文字に対する罫線は長めに書くのが良さそうです。

| | コメント (0) | トラックバック (0)

toctreeって何だ?

Sphinxのプロジェクトフォルダにある「source」フォルダには、index.rstがあります。ウェブサイトをHTMLで作ったことのある人も、そうでない人も、"index.html" はURLの一部としてよく目にすると思います。通常ウェブサイトを作る時には "index.html" がホームページ(トップページとよく言われますね)として使われます。その元が index.rst です。

index.rst に目次を書いていくと、他のコンテンツへのリンクが自動的にできていくようなイメージです。Sphinx-Users.jp のサイトを見ると、目次のツリーを挿入するための決まり文字として「TOCツリー」の説明があります。

私はここを読んでも目次のイメージをつかめませんでした。.. toctree:: の後に改行して文字列を書いていくとHTMLではどうなるのかが、絵として思い浮かばなかったのです。そこで、デベロッパーに質問してみたら、素晴らしい機能を教えてくれました。渋川よしきさんのウェブサイト(古いバージョンの訳だそうですが、ソースを見る意味では十分役立ちます)にある 「ソースコードを表示」です。

目次の書き方を知るには、目次ページを見るのが良いだろうと、「Sphinxドキュメント目次」のソースコードを表示してみると、確かに「.. toctree::」の後に、一行ずつ文字列が見えます。ソースコードとウェブサイトの表示を比べてみると、リストの一番上のレベルと、toctreeとして書いてある文字列が対応しているようです。(目次:イントロダクション、toctreeの書き方:introのように)

そこで、私は toctree を章立てを作る決まり文字として考えることにしました。

ちなみに Sphinxでは文字コードとしてUTF-8を使うため、ブラウザがIEの場合、ソースコードを表示する時はそのままだと日本語が文字化けします。[表示]-[エンコード]から UTF-8を選択して正しく表示させるか、またはFireFoxのような他のブラウザを使うと良いかもしれません。

次回は、実際に書いた toctree の例を挙げます。

| | コメント (0) | トラックバック (0)

Sphinx、index.rstを makeしてみる

sphinx-quickstart コマンドを実行して、作成するドキュメントの置き場所(プロジェクトと呼ばれます)ができたら、ひとまずファイルを makeしてみました。

何をしたか書く前に、今、渋川さんのサイト(http://sphinx.shibu.jp/)を見たところ、先週まではなかった注意が追加されていました。こちらのサイトは少し前の文書を訳したもので、最新のドキュメントを見たい方は Sphinx-Users.jp のSphinxドキュメントを確認してほしいそうです。

Sphinx 1.1 documentation

さて、Sphinxでドキュメントを作成していく時に、元のファイルの拡張子は「.rst」が基本になります。quickstartで「.txt」も選択できますが、「.rst」を意識して何かすることはほぼないので、私はそのままにしておきました。「.rst」をメモ帳(UTF-8で保存できるテキストエディタなら何でも良いそうです)で開いてみると、開発者ではない私には「.txt」と同じに見えました。

前回作成した「manual」というフォルダを開くと、sourceと buildというフォルダができています。
sourceは、HTMLページの元になる「.rst」ファイルを格納するフォルダです。
buildは、「source」フォルダにある「.rst」ファイルや画像ファイルを元にして、makeコマンドで生成されたHTMLファイルが格納されるフォルダです。

「source」フォルダには 「index.rst」というファイルができていますので、これをビルド(makeコマンドを実行する)して、表示用のHTMLファイルを生成してみましょう。

  1. [Windowsスタート]-[アクセサリ]-[コマンドプロンプト]を起動
  2. Sphinxのプロジェクトフォルダに移動
    通常、コマンドプロンプトを起動すると、ユーザーホームと呼ばれるフォルダに位置しています。
    Windows XPでは、「C:\Documents and Settings\ユーザ名」です。
  3. cd コマンドを使って、Sphinxのプロジェクトフォルダへ移動します。
    プロジェクトのフォルダが、Cドライブの直下に「manual」という名前である場合は、
    cd ../../manual
    と入力してEnterキーを押下します。
  4. 「C:\manual>」と表示されますので、その後に「make html」を入力してEnterキーを押下します。
  5. Build finished. The HTML pages are in build/html
    この文が表示されればビルドは完了です。

build フォルダの中に、htmlフォルダがあり、そこにある index.html がビルド(make htmlコマンド)によって生成されたHTMLファイルです。今回は index.rst に何も追記せずHTMLを生成したため、こんな感じのHTMLになりました。

Sphinxsample

これから「source」ファイルに、rstファイルを追加していき、make htmlコマンド実行を繰り返すことで、ドキュメントの元ファイル作成とHTML表示確認を繰り返すことができます。

| | コメント (0) | トラックバック (0)

sphinx-quickstart コマンドで設定した内容

Sphinxをインストールした後は、実際に作成したい文書のためにいくつか設定します。コマンドを実行して、ちょっとした質問にYes、Noやユーザー名やフォルダ名を回答(入力)するだけです。

参考にしたページ
slideshareで公開されている渋川さんのチュートリアル
たのしいドキュメンテーション

1. OSがWindows XPの方は、[Windowsスタート]-[すべてのプログラム]-[アクセサリ]-[コマンドプロンプト]を開きます。
2. 右向きの > の表示に続いて、sphinx-quickstart と入力します。
3. 上記リンクのスライド6枚目にあるように、プロジェクト名(ドキュメントを作っていくフォルダ名です)、著者名(自分の名前でOK)、バージョン番号(適当な数字)の三点以外は、全部 Enterキーを押していくだけでも構いません。

ただ、作り始めてみるとテキストファイルを置くフォルダと、ビルド(コマンドを実行すると、作ったテキストファイルを元に表示用のファイルを作ってくれる)結果のファイルが生成されるフォルダが同じだと、ファイルが混乱して不便なことが分かりました。作業しているフォルダ(sourceという名前になります)と、結果のフォルダ(buildという名前)は別になっている方が、単純に分かりやすいです。
そのため、quickstartで設定したフォルダを丸ごと削除して、もう一度 quickstart コマンドを実行しました。

回答した質問とその内容
これら以外はEnterキーを押すだけでした。

  • > Separate source and build directories (y/N) [n]:
    y を入力
  • > Project name:
    manual と入力
  • > Author name(s):
    自分の名前を入力
  • > Project version:
    ひとまず 0.1としました
  • > Project release [0.1]:
    何も入力しなくても、Project versionで入力した数字が自動で入っています

sphinx-quickstart コマンドでの設定が終わると、「manual」というフォルダと、その中に「source」というフォルダができています。

感じたこと: アンインストールではなくて、フォルダを丸ごと削除して、もう一度やり直せば新しい(全く別の)作業用フォルダを作れるのもいいところです。

他にも参考になるページ(Sphinx-Users.jp の解説)
プロジェクトを作る
sphinx-quickstartの詳細説明

| | コメント (0) | トラックバック (0)

より以前の記事一覧

その他のカテゴリー

Sphinx | イベント | 書籍・雑誌 | 講演・セミナー