pixiv insideは移転しました！ ≫ https://inside.pixiv.blog/

Sphinxでお手軽ドキュメント生成

キーバインドがおかしいとよく言われるemacs派のbokkoです。

今回はneoagentのドキュメンテーションに使用しているSphinxについて紹介します。

ドキュメンテーションツール Sphinx

Sphinxは様々な形式のドキュメントを生成できるツールで、reStructuredTextからHTMLやmanにはじまり、LaTeXやPDF、はてはEPUBといった形式に変換することができます。 特にHTMLドキュメントはデザインを設定一つでさまざまなテーマに切り替えることができるのでとても便利です。

Sphinxのインストール・セットアップ

SphinxをインストールするにはDebianやUbuntuであれば以下のコマンドを実行します。

1
2
3
4

$ aptitude install python-pip
$ pip install Sphinx
# あるいは
$ aptitude install python-sphinx

あとは以下のコマンドを実行すればセットアップ完了です。

1

sphinx-quickstart

sphinx-quickstartを実行すると対話形式のプロンプトが出力されていろいろな入力を求められますが、必須項目は以下の3つだけです。

  • Project name -> プロジェクト名
  • Author name -> 作者名
  • Project version -> プロジェクトのバージョン番号

セットアップが完了するとMakefileや設定ファイル(conf.py)、雛形ファイル(index.rst)ができるので、makeを実行してみましょう。以下はその出力です。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

$ make
Please use `make <target>' where <target> is one of
  html       to make standalone HTML files
  dirhtml    to make HTML files named index.html in directories
  singlehtml to make a single large HTML file
  pickle     to make pickle files
  json       to make JSON files
  htmlhelp   to make HTML files and a HTML help project
  qthelp     to make HTML files and a qthelp project
  devhelp    to make HTML files and a Devhelp project
  epub       to make an epub
  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  latexpdf   to make LaTeX files and run them through pdflatex
  text       to make text files
  man        to make manual pages
  texinfo    to make Texinfo files
  info       to make Texinfo files and run them through makeinfo
  gettext    to make PO message catalogs
  changes    to make an overview of all changed/added/deprecated items
  linkcheck  to check all external links for integrity
  doctest    to run all doctests embedded in the documentation (if enabled)
$

このようにSphinxを使うといろいろな形式のドキュメントをコマンド一つで簡単に生成することができます。

1
2

$ make html # HTML形式のドキュメントを生成
$ make man  # man形式のドキュメントを生成

実際に生成されるドキュメントの見栄えやレイアウト等はSphinxが全部面倒を見てくれるので あとは雛形ファイルのindex.rstを編集したり、新しいファイルや内容を追加していくことだけに集中できます。 これは特に手っ取り早く(CSSやJavaScriptも書かないといけない)HTML形式のドキュメントを生成したい場合に便利です。

neoagentとSphinx

neoagentではHTML形式のドキュメントと各コマンドのmanをSphinxで生成しています。

生成元の各reStructuredTextファイルや設定はこちらに、 実際に生成したHTMLドキュメントはこちらにありますので、Sphinxをこれから使おうと思っている方は参考にしてみてください。