Sphinxでドキュメント作成をする環境を作ってみた

   2017/04/30

Sphinxの存在は、結構前から知っていましたが、プロジェクト等で使うチャンスがなかった。 複数人でのプロジェクトであれば、どのドキュメント作成ツールを使うかは、他のメンバーの好みもあり独断では決められないことが多いと思います。 先日たまたま一人で開発及びドキュメントを作成する必要にかられ、Sphinx-Users.jp等を参考にSphinx環境を作ってみました。 ここでは、以下の環境での使用を前提にしています。

  • CentOS6.8 x86_64

Install

まずは、必要なツールをインストール。

# yum install epel-release
# yum install python-setuptools

続いてpythonのパッケージ管理ツール easy_installでsphinxのインストール。

# easy_install sphinx

Running Sphinx-1.5.3/setup.py -q bdist_egg –dist-dir /tmp/easy_install-W4m6H4/Sphinx-1.5.3/egg-dist-tmp-qVbGjZ
ERROR: Sphinx requires at least Python 2.7 or 3.4 to run.
error: Setup script exited with 1

すると↑のようなエラーとなった。 どうやらpython2.7以上のバージョンで無いといけないらしい。 いろいろ調べてみるとCentOS6で入っているphython2.6をバージョンアップをするのはNGのようです。 yumがうまく動作しなくなったりするらしい。 そこで一時的にpython2.7を実行できるようなことを試してみた。 以下の2つをyumでインストールする。

# yum install centos-release-scl-rh
# yum install python27

この状態では、普通にpythonを実行するとpython2.6が実行される。 そこで次のコマンドを実行するとテンポラリでphython2.7が使えるようになるようです。

# scl enable python27 bash

常に使える状態にしておきたいときにはsource /opt/rh/python27/enable.bashrcに書いておくとよいらしい。 もう一度、”easy_install sphinx” を実行したら無事インストールできた。 ブロックダイアログを利用するために”sphinxcontrib-blockdiag” もインストールしておく。

# easy_install sphinxcontrib-blockdiag

The headers or library files could not be found for jpeg,
a required dependency when compiling Pillow from source.

インストールしてみたら、↑のエラーがでた。 jpegのヘッダーファイルが必要らしいのでyumでインストール。

# yum install libjpeg-turbo-devel

これで”sphinxcontrib-blockdiag”もインストール完了。 作成したドキュメントをPDFにもしたいので”rst2pdf”とフォントをインストールした。

# easy_install rst2pdf

フォントは他のサイトを参考に以下の2つをインストールした。

  • LVゴシックフォント
  • IPAフォント

LVゴシックフォント

以下からLVゴシックフォントをダウンロード

# wget https://ja.osdn.net/projects/vlgothic/downloads/62375/VLGothic-20141206.zip

# unzip VLGothic-20141206.zip
# cd VLGothic-20141206
# cp *.ttf /usr/share/fonts/

IPAフォント

# wget http://ipafont.ipa.go.jp/old/ipafont/IPAfont00303.php
# unzip IPAfont00303.zip
# cd IPAfont00303
# cp *.ttf /usr/share/fonts/

以上でインストールは完了。

使い方

まずは、作成していくドキュメント用のディレクトリを作成します。

# mkdir my_document
# cd my_document

ドキュメント作成用のディレクトリでプロジェクトを作成します。

# sphinx-quickstart 

sphinx-quickstartを実行すると、以下のように対話形式でいろいろ聞かれますので、必要に応じて質問に答えていきます。 何か記述する必要があるヶ所には[必須]と書いておきます。

Welcome to the Sphinx 1.1.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:

ドキュメントを作成するパスを設定。 そのままエンター。

You have two options for placing the build directory for Sphinx output.
Either, you use a directory “_build” within the root path, or you separate
“source” and “build” directories within the root path.
> Separate source and build directories (y/N) [n]:

rootパスに_buildディレクトリを作成するか、sourceとbuildディレクトリ分けて作成するかの選択。 ここでは、y を選択。

Inside the root directory, two more directories will be created; “_templates”
for custom HTML templates and “_static” for custom stylesheets and other static
files. You can enter another prefix (such as “.”) to replace the underscore.
> Name prefix for templates and static dir [_]:

もう2つディレクトリが作成される。上でSeparate source and build directory (y/N) [n]: y にするとroot/souceの下に、また n にするとroot直下で HTMLテンプレート用に”_templates”、スタイルシート用に”_static”ができます。 ここでは、このディレクトリのプレフィックスを変更できる。 特に気にならないのでそのままエンター。

The project name will occur in several places in the built documentation.
> Project name:
> Author name(s):

[必須]Project nameとAuthor name(s)は必須の項目です。 何らしらタイプします。 ここでは、DocTest、puchiとそれぞれタイプしてみました。

Sphinx has the notion of a “version” and a “release” for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don’t need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]:

[必須]Project versionも必須項目です。 説明にあるようにSphinxは、考え方としてversionとreleaseを別管理できるようにしています。 必要ない場合は同じ値を記述すればいいようです。ここではversionとreleaseを共に1.0としました。

ここ以降の選択肢は、全てデフォルトのままエンターをタイプしました。 ドキュメントroot パス配下には以下の様なファイルができているはずです。

./build
./source
./source/_static
./source/index.rst
./source/_templates
./source/conf.py
./make.bat
./Makefile

./source/index.rst ファイルにサンプルが入ってますので例えば

.. DocTest documentation master file, created by
sphinx-quickstart on Thu Mar  9 00:43:58 2017.
You can adapt this file completely to your liking, but it should at least
contain the root toctree directive.

Welcome to DocTest’s documentation!
===================================

Contents:

.. toctree::
:maxdepth: 2

HogeHoge

Indices and tables
==================

* :ref:genindex
* :ref:modindex
* :ref:search

とHogeHogeとだけ入力してみます。 ドキュメントrootパスの直下に行き、make html を実行するとbuildディレクトリの下にhtmlフォルダができ、そのフォルダ内にあるindex.htmlを開くと以下のようになります。

 

Contents:の下にHogeHogeと入っているのが分かります。 今回は長くなりましたのでこのくらいにして、その他については次回にしたいと思います。

 

  • このエントリーをはてなブックマークに追加
  • Pocket

関連記事-こちらもどうぞ

  • 記事はありませんでした。これから充実させていきますのでお楽しみに!

この記事へのコメントはこちら