はじめに
本エントリで説明すること
- Python製のドキュメント作成ツール「Sphinx」の導入から簡単なドキュメント生成まで
- ホットリロードするモジュール「sphinx-autobuild」のインストールと使い方
- テーマの変更方法
本エントリで説明しないこと
- python3とpipのインストール方法
- reStructuredTextについての細かい説明
- MkDocsのような他のドキュメント作成ツールとの比較
- Sphinxの細かいオプション等
前提
- python3系をインスールしていること
筆者の環境
- macOS Catalina 10.15.3
- Python 3.7.4
venvでSphinx用の仮想環境を作成する
Sphinx用の仮想環境のディレクトリを作成します。
ディレクトリ名は任意です
$ mkdir sphinx
作成したディレクトリに移動し、仮想環境を作成します
仮想環境名はここではsphinx-venvとしておきます。
$ cd sphinx
# 「python3 -m venv 仮想環境名」とすることで仮想環境を作成できます。
$ python3 -m venv sphinx-venv
仮想環境のディレクトリに移動し、仮想環境を有効にする
$ cd sphinx-venv
$ source bin/acitvate
pipでsphinxをインストールする
$ pip install sphinx
sphinxのプロジェクトを作成する
sphinx-quickstartを打つと、ズラズラとメッセージが流れて、対話的に何個か聞かれます。
ひとまず特にこだわりがなければ、下記のように設定すればよいと思います。
$ sphinx-quickstart
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]:y
> プロジェクト名: test-project
> 著者名（複数可）: test-author
> プロジェクトのリリース []: 1.0.0
> プロジェクトの言語 [en]: ja
私の実行環境では、上記の通りに日本語で聞かれましたが、
環境によっては下記のように英語で聞かれます。
$ sphinx-quickstart
> Separate source and build directories (y/N) [n]:y
> Project name: test-project
> Author name(s): test-author
> Project version []: 1.0.0
> Project language [en]: ja
htmlファイルを生成する
まずはデフォルト状態で、htmlファイルを生成します。
htmlファイルを生成するには、Makefileがある場所で以下のようにコマンドを打ちます
$ make html
これで、buildディレクトリ以下にindex.htmlというファイルが生成されますので、
任意のブラウザで表示させてください。
コンテンツを追加する
Sphinxでは、コンテンツを追加するために、
- 新しくファイルを作成し、
- トップページに登録する
必要があります。
新しくファイルを作成する
「source」配下に適当な名前のファイルを作成します。
ここでは、ファイル名を「test.rst」とします。
適当に中身を書きます。
===================
ここにタイトルを入れる
===================
大見出しを入れる
---------------
- 箇条書きです
- 箇条書きです
トップページに登録する
「source」配下にある「index.rst」がトップページになっています。
このファイルを編集し、先程作成した「test.rst」を登録します。
編集は以下のように、ファイル名と同じ名前を追記してください。
.. toctree::
:maxdepth: 2
:caption: Contents:
.. toctree::
:maxdepth: 2
:caption: Contents:
test
ここで、もう一度、「make html」を実行すると、トップページに
「ここにタイトルを入れる」がリンク付きで表示されるようになります。
こちらのリンクをクリックすると、test.rstに記載した内容を見ることができます。
【おまけ】ホットリロードできるようにする
Sphinxでは通常、ドキュメントを編集した後、「make html」と打ち、ブラウザをリロードし直す必要があります。これは地味に面倒ですので、ドキュメントを編集したら、自動でhtmlファイルを生成し、自動でリロードが掛かるようにします。
$ pip install sphinx-autobuild
インストール後は、「Makefile」があるディレクトリで以下のコマンドを打ちます。
# sphinx-autobuild [xxx.rstがあるディレクトリ] [htmlファイルが生成されるディレクトリ]
# 本エントリでは、以下のようになります
$ sphinx-autobuild source build
すると、ローカルでサーバが起動しますので、URL（http://localhost:8080）をブラウザで表示すると、作成されたhtmlファイルを閲覧できます。
【おまけ】テーマを変える
「source」ディレクトリ配下にある「conf.py」の下の方に以下の記述があります。
html_theme = 'alabaster'
'alabaster'のところを書き換えることで、テーマを変えることができます。
なお、'alabaster'はデフォルトのテーマになっています。
Sphixでは標準の以下のテーマが用意されています。
- alabaster
- default
- sphinxdoc
- scrolls
- agogo
- nature
- pyramid
- haiku
- traditional
- bizstyle
サードパーティ製のテーマを設定することも可能です。
例えば、マテリアルデザインのテーマを設定したい場合は以下のようにテーマをインストールします。
$ pip install sphinx-theme-material
テーマをインストールしたら、conf.pyを以下のように設定します。
設定後、テーマがマテリアルデザインに変わっています。
html_theme = 'material'