目次

前のトピックへ

note.sicafe.net / Sphinx Memo

次のトピックへ

reST 文法メモ

このページ

インストールと初めてのプロジェクト

ノート

参照および引用元 Sphinx-Users.jp CentOS 5.5にsphinxをインストール

Mac OS X, Linuxへのインストール

MacPorts による install

Mac OS Xの MacPorts を利用しているのであれば

$ sudo port install py26-sphinx

このままだと実行時のパスに追加されないため、python_selectもインストールして、python2.6が標準で使われるようにしてみましょう。

$ sudo port install python_select
$ sudo python_select python26

which sphinx-quickstart が応答を返してくればインストール完了ですが、 自分の環境ではアプリケーションのPythonのバージョン番号がついてしまうので、 以下のように手でシンボリックリンクを張りました。

$ sudo ln -s /opt/local/bin/sphinx-autogen-2.6 /opt/local/bin/sphinx-autogen
$ sudo ln -s /opt/local/bin/sphinx-build-2.6 /opt/local/bin/sphinx-build
$ sudo ln -s /opt/local/bin/sphinx-quickstart-2.6 /opt/local/bin/sphinx-quickstart
$ which sphinx-quickstart
/opt/local/bin/sphinx-quickstart

pythonパッケージ管理ツール pip による install

以下の手順で、pipを通じてsphinxの最新版をインストールできる。 おそらく Linux の環境の場合は、yum や rpm よりもこちらの方が確実に最新版を 入手できると思われる。

# yum install python-pip python-setuptools
# pip-python install sphinx

yum による install

EPELリポジトリを通じてインストールする事が可能だが、インストールされるSphinxのバージョンが低いので [2] 、pipを通じたインストールがオススメ。

# rpm -ivh http://ftp.riken.jp/Linux/fedora/epel/5/i386/epel-release-5-4.noarch.rpm
Retrieving http://ftp.riken.jp/Linux/fedora/epel/5/i386/epel-release-5-4.noarch.rpm
warning: /var/tmp/rpm-xfer.gP0QTr: Header V3 DSA signature: NOKEY, key ID 217521f6
Preparing...                ########################################### [100%]
   1:epel-release           ########################################### [100%]

# yum install python-sphinx

sphinx-quickstartの実行

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

$ sphinx-quickstart

いくつか質問されます。絶対に回答しなければならないのは、次の項目です。 後はEnterキーだけで大丈夫です。

  • プロジェクト名
  • バージョン番号
  • 著者の名前
$ sphinx-quickstart
Welcome to the Sphinx 1.0.7 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]:

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 [_]:

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

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: 0.1
> Project release [0.1]: 2011/04/10

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]:

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]: n

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

終わった後以下のようにファイルが生成される

$ ls
Makefile       _build          _static         _templates      conf.py         index.rst

言語環境の設定

config.pyを開いて以下の行を変更します。

language = 'ja'

これでテンプレートから自動生成される部分が日本語化されます。

HTMLファイル化

HTMLファイルの生成

ファイルができたら、下記のコマンドを実行して、HTMLファイルを作ってみましょう。

$ make html

_build/html フォルダ内にHTMLが生成されます。

HTMLファイルのテーマを変える

conf.py ファイル内の以下の部分を変えれば良い

html_theme = "default"
html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

デフォルトのテーマはオフィシャルサイト参照 * HTML theming support

脚注

[1]注意: 大量の関連パッケージがインストールされるので、事前に確認しておくことをオススメします(汗
[2]2011/04/10現在、 yum install python-sphinx でインストールされるパッケージは Sphinx-0.4.2-py2.4.egg