読者です 読者をやめる 読者になる 読者になる

はじめてのSphinx

開発系のドキュメントを作成する必要があり、気になっていたSphinxを試してみた。


Sphinxをはじめよう :: ドキュメンテーションツール スフィンクス Sphinx-users.jp

インストール

すでにWindows + Cygwin + Python 2.6.8の環境が手元にあったので、インストール自体は以下のコマンドですぐ完了

$ easy_install sphinx

プロジェクトの作成

$ sphinx-quickstart

たくさんの質問をされるが、

  • Project name
  • Author name(s)
  • Project version
  • Project release

以外全てデフォルトのままで、プロジェクトを作成した。

ページ作成、はじめてのreST記法

チュートリアルを進めながらページを作成した。
rstファイル変更して、

$ make html

の繰り返し。

日本語を使用する場合はUTF-8である必要あり。

WARNING: undecodable source characters, replacing with "?":

と怒られます。

あとはひたすら、reST記法に慣れる。

途中、

WARNING: Title underline too short.

というエラーが。

ありがとうございます。↓で解決。
Sphinxでドキュメントを書くためreST記法に入門した - kk_Atakaの日記

メニューの日本語化

sphinx-users.jp のトップにあるスクリーンショットでは左メニューが日本語化されているのに、生成されたドキュメントは日本語化されていない・・・・。
調べてみたところ、ソースフォルダにある「conf.py」に設定項目があるとのこと。

#language = None

language = 'ja'

に変更し、生成しなおすと、、、おお、日本語化された。。。

使ってみた感想

  • PukiWikiRedmineのTextileに加え、また新しい記法が・・・・orz
  • 見出し記法がrst上でも「見出しっぽい」のがいいね。
  • HTMLの他、PDF, ePubにもエクスポートできちゃうのはいいね。

成果物

ひっそりこちらに
https://github.com/gliani/sphinx-quickstart