Tottoto Note

少しずつ移転します → https://tottoto.net/

Macでドキュメント生成ツール-Sphinx-を使う (1)

Macで美しいドキュメントを生成するPythonツールであるSphinxを導入する手順について解説します.ここでは

を利用した導入方法を紹介します.Homebrewは使っていないので分かりません……

導入環境

私が導入したときの環境は以下のようになります.

Sphinxの導入方法

Python3.4に対応したSphinxをインストールします.

sudo port install py34-sphinx

自動的に依存関係をチェックしてくれるのでPython3.4もインストールしてくれます.

次に,コマンドを設定します.

sudo port select --set python python32
sudo port select --set sphinx py34-sphinx

MacPorts版のPythonではライセンスの関係でreadlineが内蔵されていないので別に入れなければなりません.実際にSphinxを使う上で困ったことになります.

sudo port install py34-readline

以上で終わりです.

非公式の拡張機能はPython2で書かれていることが多く,その場合はpython3だとエラーを返してしまいます.
非公式の拡張機能を使う可能性があるならPython2.7を使う方が無難かもしれません.

sudo port install py27-sphinx
sudo port select --set python python27
sudo port select --set sphinx py27-sphinx
sudo port install py27-readline

Sphinx拡張機能をインストールする際にパッケージを管理するpipを使うことが多いのでここで導入してしまいましょう.

sudo port install pip-34

これでSphinxを使用する準備が整いました.pip-34はpipで使えるように.bash_profileに

alias pip='pip-3.4'

と書いておくと便利です.Python2.7のときも同様にして

sudo port install pip-27
alias pip='pip-2.7'

とすればいいと思います.

使ってみよう

Sphinxプロジェクトの作成

実際にSphinxプロジェクトを作成して美しいドキュメントを作ってみましょう.適当なディレクトリを作成します.ここではdocと名付けました.このdocがプロジェクトのルートディレクトリとなります.

mkdir doc
cd doc

それではSphinxを初めます.コマンド

sphinx-quickstart

を実行すると,Sphinxプロジェクト生成のユーティリティが起動します.対話型で初期設定を進めていくのですが,殆どデフォルトで問題ありません.しかし,折角なので個人的に重要なところだけ解説します.

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

Sphinxドキュメントのルートディレクトリの設定です.デフォルトではカレントディレクトリが指定されているので何もせずにEnterを押しましょう.

なお,readlineをインストールしていないと

Enter the root path for documentation.
[35m> Root path for the documentation [.]: [39;49;00m

と変な文字が出てしまいます.表示がおかしいだけでなく動きも以上になるのでCtrl-cで中断してMacPortsからpy34-readlineをインストールして下さい.

次は

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

です.これはソースファイルとビルドして出力されたドキュメントのディレクトリの構成を決めるものです.yを選ぶとルートディレクトリにソースファイル用と生成されたドキュメント用のディレクトリがそれぞれ分けて作られ,nを選ぶとルートディレクトリがソース用のディレクトリとなり,その中にドキュメント用の_buildというディレクトリが作られます.

yのとき

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

これは設定ファイルやカスタムファイルをいれるディレクトリのプレフィックスを決めるものです.先ほどの画像で「_static」などと「_」で始まっているものがこれにあたります.デフォルトで良いでしょう.

The project name will occur in several places in the built documentation.
> Project name: my_project_name_here # 入力
> Author name(s): 
* Please enter some text.
> Author name(s): my_name_here # 入力

Sphinx文章のプロジェクト名と著者名です.これは必須ですのでEnterを連打していても入力しそこねることはないので安心して下さい.上記のように再度質問されます.

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.0くらいで良いのではないでしょうか.

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: ja

文書の言語を決めます.日本語の文書であればjaにしておきましょう.

'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'

がサポートされています.

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

ソースファイルの拡張子を決めます.restructuredtext形式で書くことになるので,この形式の拡張子である.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]: 

HTML出力したときのトップページのファイル名を決めます.デフォルトではindexが指定されているのでこのままにしたときはindex.htmlがトップページとなります.

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

ePub出力の初期設定をするかを決めます.

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]: 
> sphinx: 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]: y
> mathjax: include math, rendered in the browser by MathJax (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]: 

それぞれの拡張機能の設定をするかどうかを決めます.私はLaTeX数式を画像に変換して埋め込んでくれるpngmathのみを有効化しました.pngmathを有効化するとMathJaxは有効化出来ません.

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

Makefileを作るかどうかです.デフォルトの通り必ず作っておきましょう.これを作らないとmake htmlという簡単なコマンドでHTMLを作ることが出来なくなってしまいます.Windows command fileはウィンドウズ用のmakefile.batを作るかどうかですが,あって損はないのでそのままにしておきましょう.


以上でユーティリティは完了です.結局すべてを解説してしまいました.


Makefileをいじっておきます.Sphinxはタイムスタンプを管理しているので編集していないファイルに対応する部分はビルドしません.しかし最初色々と設定を試行錯誤しているときは強制ビルドをして欲しい場合がしばしばあります.以降ソースファイルは分割すると設定したものとして進めていきます.

HTMLのビルド

doc/Makefile

html-a:
	$(SPHINXBUILD) -a -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

と追加して下さい.似たような記述がある中に紛れ込ませればいいと思います(空白はTABなので注意).

これでmake html-aで強制リビルドができるようになります.

それではdoc(Makefileがあるディレクトリ)に移動して

make html-a

します.これで doc/build/html 以下にHTMLで構成されたWebサイトが出力されます.index.html がトップページとなります.これに対応するものは doc/source/index.rst ですこちらを編集してから make すれば index.html に反映されます.

Sphinxの導入とテストができたので今回はここまでにします.

続きはこちら

rwilyp.hatenablog.com