Sphinxを利用したドキュメント開発環境の構築方法

動作環境

CentOS 7
メモリは1GB程度でもOK
Python 3.6

構築手順

Python 3 + pip投入

$ sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum install -y https://centos7.iuscommunity.org/ius-release.rpm
$ sudo rpm --import /etc/pki/rpm-gpg/IUS-COMMUNITY-GPG-KEY
$ sudo yum install -y python36u python36u-devel python36u-libs

# python3と叩けばpython3.6を実行できるようにする
$ sudo ln -s /usr/bin/python3.6 /usr/bin/python3

$ sudo yum install -y python36u-pip
$ sudo yum makecache fast

バージョン確認

$ python3  --version
Python 3.6.5

$ python3 -m pip --version
pip 9.0.1 from /usr/lib/python3.6/site-packages (python 3.6)

Sphinx投入

$ sudo python3 -m pip install Sphinx

Sphinxの各機能の投入

参考元
- Markdown support
- sphinx_rtd_theme

$ sudo python3 -m pip install recommonmark
$ sudo python3 -m pip install sphinx_rtd_theme

ドキュメント開発

次のリンク先を参照してドキュメントを作成します。

$ mkdirs <path-to-Sphinx-work-directory>
$ cd <path-to-Sphinx-work-directory>
$ sphinx-quickstart

sphinx-quickstartは対話型でsource/conf.pyを作成します。
そのとき、Getting Startedに沿って作業する場合、autodoc拡張機能についてはyesで答えます。

続いて、source/index.rstのtoctreeディレクティブにドキュメント化するファイルを追加したりしてから、最後に次のコマンドでHTMLドキュメントを作成してくれます。

$ make html