// Net planet-es V2

ブログは一ページに収まる範囲で、技術情報やチップス情報を載せるのはお手軽で便利なのですが、ある程度文章が必要な複数ページのドキュメントを作成しようとするとリンクの設定や索引付け、等が面倒になります。

ある程度構造化されたまとまったhtmlドキュメントを作成するツールがないかなぁといろいろ調べていたのですが、最終的にSphinx を使うことにしました。

なので、この記事では、Sphinx導入の超簡単な覚書を残しておきます。

1. Python のインストール

Sphinx は Python で動作するので、まずPython をインストールします。https://www.python.org/downloads/ から最新バージョンをダウンロードしました。インストーラーがあるので、簡単にインストールできます。 インストールウィザードの最初の画面で Pythonのプログラム までのパスを 環境変数の PATH に追加するオプションがあるので、忘れずにチェックしてインストールします。 忘れた場合は、コマンドプロンプトからPythonを使用できるように手動でPATHにPythonまでのパスを追加しておきます。

コマンドプロンプトで python -V と入力してバージョンが表示されれば成功です。

2. Sphinx のインストール

Sphinxは Pythonのパッケージ管理ツールを使って簡単にインストールできます。手順に関しては、 http://www.sphinx-doc.org/en/stable/install.html#install-the-pip-command に掲載されています。インストラクション通り、次のコマンドを入力すれば簡単にインストールできます。html 形式だけでなくePub 形式でドキュメントを作成したい場合は Pillow というパッケージも必要みたいです。その場合は Pillow もインストールしてあげてください。

pip install sphinx

インストール後、 spphinx-build -h コマンドを実行するか、 sphinx-quickstart --version でsphinx のバージョンを確認できます。

3.サンプルプロジェクトを作成

sphinxまでインストールしたら、試しにプロジェクトを作成してみます。例えば次のコマンドを実行します。

sphinx-quickstart sample

すると、いくつか質問がされるので、y/n で答えていくとプロジェクトフォルダーを作成できます。指定するオプションの内容はデフォルトのままEnterキーをたたけば問題ないですが、 Project name, Author name, Project version は設定したほうがいいみたいです。そのほか、 Project language は ja を設定すると、make html コマンドでHTMLを生成されるときに、自動生成されるテキストが日本語になります。

無事プロジェクトフォルダーが作成されると、フォルダーの中にファイルが作成されます。

make html とすると、 htmlファイルを作成できるようになります。reStructuredText でドキュメントを作成してい久野ですが、使える構文などは、このページなどを参照できます。

Read the Document theme for Sphinx で公開されているカスタムテーマをインストールしたい場合は、下記GitHubのページが参考になります。

Read the Docs theme for Sphinx 
https://github.com/rtfd/sphinx_rtd_theme