Python+Sphinxによるドキュメント生成【Windows+PyCharm環境】

プロジェクトのドキュメント作成を何で作るべきか色々考えていたのですが、前から気になっていたSphinxを一度使って見たのでインストール手順から使用感まで紹介したいと思います。

Sphinxの記法もすぐ忘れてしまいそうなので、よく使う章・テーブル・文字装飾などを中心に備忘録的にまとめます。

Sphinxのインストール

Sphinxのインストールは環境ごとに色々違いがあると思いますが、今回はWindows端末にAnaconda Navigatorで生成した仮想環境にインストールします。
linuxやmacでもPythonが動作する環境であれば使用可能です。今回はAnaconda Navigatorで既に仮想環境の構築や、Pythonの設定が済んだうえでの流れとなります。

インストール自体はAnaconda Navigatorを使用する場合はGUIでインストールするだけです。以下画像の通りですので説明は省略します。

Sphinxのバージョン確認

Sphinxのインストールが出来ましたら、ターミナルから以下のコマンドでバージョン確認してみます。(Anaconda Navigator上からも確認は出来ます)
2020/06時点では最新が3.0.4でした。

Sphinxのプロジェクト生成

まずは、プロジェクトを生成する任意ディレクトリへ移動します。

(例)

Sphinxのプロジェクト生成

sphinx-quickstartコマンドでプロジェクトを作成する事が出来ます。sphinx-quickstartはパラメータを指定してプロジェクトを自動生成するパターンと対話式で生成するパターンがあります。
(どちらも結局指定する内容は同じです。)

設定が必要となる項目は以下の通りです。

  • Project name:任意のプロジェクト名
  • Author name:任意の管理者名
  • Project release:任意のリリース番号
  • Project language:ja

プロジェクトの生成が完了すると、カレントディレクトリにファイルが生成されています。

今回設定した内容は、 ./source/conf.py に反映されていますので、作成後にプロジェクト名などを変更したい場合はこちらを編集します。

Sphinxの使い方 サンプルコード

記載内容はプロジェクトによって異なると思いますが、以下は割と共通的に conf.py で設定しておいた方が良さそうな記載。

サイドバーのソースコードを表示 を消す

フッターのコピーライトを消す

フッターの「このドキュメントはSphinxで作成しました」を消す

ドキュメントの実態は、.rst 形式のファイルです。こちらの中身をSphinxの記法で記載する事になります。.rst形式はテキストファイルですので、PyCharmからも編集が可能で、PyCharmではリアルタイムに編集内容を描画してくれる機能もあります。

ページ追加

./source/index.rst と同様に、任意の hogehoge.rst を追加します。ページごとの内部リンクは後述のハイパーリンクで繋ぎます。

Sphinxの記法は膨大で全てを記載するのは難しいので、ここではよく使う代表的な記法をいくつかご紹介します。より細かい使い方については以下より本家のリファレンスをご覧下さい。
https://www.sphinx-doc.org/ja/master/contents.html

章・番号表示

オプションは沢山ありますが、適宜必要なものを使えば大丈夫です。

コードのシンタックスハイライト

言語はPython,rstだけでなく、c言語,javascriptやhtml,cssなどpygmentsに登録されている言語がすべてカバーされます。

見出し・セクション

テーブル表示1

改行はハイフンで改行できます。

テーブル表示2

表の横幅(文字数)合わせに注意

テーブル表示3

幅調整を考えるとcsv-tableが一番便利な気がする。

ハイパーリンク

画像挿入

キャプションを付けたいときはimage → figureに変えるとキャプションのオプションを付けることが出来る。並べたり、回り込みの制御などの細かい指定も出来ます。
https://sphinx-users.jp/reverse-dict/images/index.html

CSSによる文字色・サイズ・強調などのhtml用装飾

スタイルシートを利用して文字装飾なども可能です。(LaTexによるPDF出力では反映されませんでした)
./source/_static/ 以下に任意のcssファイルを作成して、conf.pyで読み込みます。(ここではbase.cssとします。)

■conf.py

■base.css

■任意のrstファイルでの使い方

赤文字にしてみた例です。

強調(太字)・強い強調

注釈

他のファイルをインクルードする

リスト(箇条書き)

*、+、-など。

番号付きリスト(箇条書き)

Sphinxドキュメントのテーマ変更

Sphinxでドキュメントを生成する際にhtmlのテーマを選ぶことが出来ます。htmlテーマは既存の組み込みテーマと、独自に追加したテーマも設定する事が出来ます。
既存のテーマは以下の種類があり、初期値としては、alabasterというテーマが設定されています。

  • alabaster
  • classic
  • sphinxdoc
  • scrolls
  • agogo
  • traditional
  • nature
  • haiku
  • pyramid
  • bizstyle

テーマは ./source/conf.py の html_theme の項目で変更する事が出来ます。

bootstrapのテーマに変更

テーマは、bootstrapのテーマも設定する事が可能です。bootstrapテーマを設定する場合は、テーマをインストールしたうえで上記同様に conf.py を以下のように変更するだけです。

■インストール

■conf.py

ドキュメントの出力方法

html出力する場合

Sphinxで作成したドキュメントをhtml形式で出力する場合は、make html で出力出来ます。
出力先は ./build/html ディレクトリ以下に出力されます。

[出力結果画像]

pdf出力する場合

SphinxでドキュメントをPDF形式で出力する方法の紹介です。PDF出力する方法はいくつかありますが、Sphinx単独では出来ません。一番おススメされていた方法でうまくできたのでLaTeXを利用したPDF出力方法を記載します。

LaTexのインストール

まずは、以下のLatex配布サイトにアクセスし「download from a nearby CTAN mirror」をクリックします。アクセス元から最適なダウンロード先が表示されます。
http://www.tug.org/texlive/acquire-iso.html

最新版(2020年の場合は、texlive2020.iso )をクリックしダウンロードします。ちなみにファイル容量が3.7GBと大きいのでダウンロード時間や保存先容量にはお気を付けください。

isoファイルのダウンロードが完了したら、isoをダブルクリックで開き、内部の install-tl-windows.bat をダブルクリックで実行するとインストールが進みます。インストールは以上です。

LaTexのバージョン確認

LaTexが正しくインストールされた場合は、ターミナルで以下のコマンドを打つとインストールされたLaTexのバージョンが確認できます。以下のように表示されれば大丈夫です。

SphinxでのLaTexの設定

PDF出力するための設定としては、conf.pyに以下の記述を追加します。

SphinxでのPDF出力実行

PDF出力はhtmlの際と同様にmakeコマンドを利用します。

[出力結果画像]

ちなみにSphinxではhtmlやpdf以外にもWord(docx)などの形式でも出力できるようです。

Sphinxを使ってみたまとめ

Sphinxの生成ファイル類もプロジェクトディレクトリに含めることでGitで管理すれば変更差分も分かりやすく使い勝手も良くメリットはあると感じました。エディタにも制限は無く、PyCharmからも操作できリアルタイムに描画してくれるところもポイントが高かったです。ただ、PyCharm上での描画はWarningが結構出たりします。

htmlドキュメントは検索機能もあるので単純なマニュアルよりも使い勝手はいいように思います。

Sphinxは日本語のリファレンスマニュアルも充実しているので、大概の事は調べれば出来そうです。記法や用語はすぐ忘れてしまうので、抽出したリファレンスを見ながらになってしまいますが慣れてくればドキュメント生成の大半はSphinxに集約しても良いかなと思いました。