Sphinx 導入

created at 2019-08-12 17:11+0900

Sphinx とは reStructuredText というマークアップ言語で記述したドキュメントをいろんなフォーマットで出力できちゃう便利ツール。

http://www.sphinx-doc.org/en/master/

出力できるのは次のフォーマット

  • HTML (including Windows HTML Help)

  • LaTeX (for printable PDF versions)

  • ePub

  • Texinfo

  • manual pages

  • plain text

複数のファイルに分けて書いたドキュメントを1ページのHTML(singl HTML)として出力することも可能。

Sphinx インストール

pipenv 仮想環境作成

pipenv プロジェクトディレクトリへ移動

cd ~/Documents/XDOCS && ls -la && pwd

pipenv 仮想環境構築

pipenv install
pipenv --venv

pipライブラリインストール

Sphinx本体

pipenv install sphinx

ダイアグラム作成ライブラリ

pipenv install sphinxcontrib-blockdiag sphinxcontrib-seqdiag sphinxcontrib-actdiag sphinxcontrib-nwdiag
pipenv install sphinxcontrib-plantuml

テーマ

pipenv install sphinx-bootstrap-theme

Sphinx Bootstrap Theme https://github.com/ryan-roemer/sphinx-bootstrap-theme

テーマのデモサイト https://bootswatch.com/3/

Sphinxプロジェクト作成

pipenv 仮想環境へ入る

pipenv shell

Sphinxプロジェクトを作成するディレクトリへ移動

cd ~/Documents/XDOCS/conohaVps_2019 && ls -la && pwd

Sphinxプロジェクト作成

sphinx-quickstart --quiet -p conoha -a r-square.net -v 2019 -r 0.1 -l ja --sep --ext-todo --ext-intersphinx --ext-ifconfig --ext-viewcode --makefile --no-batchfile

オプションの説明

--quiet

sphinx-quickstartコマンドの対話モードをスキップする。-p, -a, -v オプションが必須になる。

-p <project_name>

プロジェクト名(project_name)を指定する。

-a <auther_name>

作者名(author_name)を指定する。

-v <version>

バージョン番号(version)を指定する。

-r <release>

リリース番号(release)を指定する。

-l <language>

言語を指定する。日本語:ja, 英語:en

--sep

ソースディレクトリとビルドディレクトリを分ける。

--ext-todo

拡張機能todoを有効にする。todoディレクティブを記述しておき、todoリストを表示できるようにする。

--ext-intersphinx

拡張機能intersphinxを有効にする。プロジェクトをまたいで、リンクできるらしい。

--ext-ifconfig

拡張機能ifconfigを有効にする。ビルド対象に含めるとか含めないとか条件付けできるらしい。 いわゆるネットワークコマンドのifconfigとは関係ない。

--ext-viewcode

拡張機能viewcodeを有効にする。docstringからAPIドキュメントを作った場合ソースへのリンクを表示するらしい。

--makefile

Makefileを作成する。make htmlでhtmlファイルがビルドできるようになる。

--no-batchfile

batファイルを作成しない。

実行前

(XDOCS) bash-3.2$ ls -la
total 16
drwxr-xr-x  4 ricotta  staff   128  8  6 04:53 .
drwxr-xr-x  7 ricotta  staff   224  8  6 06:17 ..
-rw-r--r--@ 1 ricotta  staff  6148  8  6 04:53 .DS_Store
drwxr-xr-x  4 ricotta  staff   128  8  6 04:53 source

実行結果

終了:初期ディレクトリ構造が作成されました。

マスターファイル ./source/index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。

(XDOCS) bash-3.2$ ls -la
total 24
drwxr-xr-x  6 ricotta  staff   192  8  6 06:19 .
drwxr-xr-x  7 ricotta  staff   224  8  6 06:17 ..
-rw-r--r--@ 1 ricotta  staff  6148  8  6 04:53 .DS_Store
-rw-r--r--  1 ricotta  staff   638  8  6 06:19 Makefile
drwxr-xr-x  2 ricotta  staff    64  8  6 06:19 build
(XDOCS) bash-3.2$
(XDOCS) bash-3.2$ tree
.
├── Makefile
├── build
└── source
    ├── 00_setup.rst
    ├── 01_maintenance.rst
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

4 directories, 5 files
drwxr-xr-x  8 ricotta  staff   256  8  6 06:19 source
(XDOCS) bash-3.2$
(XDOCS) bash-3.2$ cat Makefile
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
     @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
     @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Sphinxビルド設定をカスタマイズ

Sphinxプロジェクトを作成するとsourceディレクトリ下にconf.pyファイルが作成される。

テーマを変更したり、拡張機能を追加したり、なんやかや設定変更したりする場合、conf.pyを編集する。

## 変更箇所のみ抜粋 ##
import sphinx_bootstrap_theme
import os
import sys

today_fmt = '%Y-%m-%d %H:%M:%S %Z'

extensions = [
'sphinx.ext.todo',
'sphinx.ext.intersphinx',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
### --- additional from here --- ###
'sphinxcontrib.blockdiag',
'sphinxcontrib.seqdiag',
'sphinxcontrib.actdiag',
'sphinxcontrib.nwdiag',
'sphinxcontrib.plantuml',
### --- additional up to here --- ###
]

html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_theme_options = {
    'navbar_class': "navbar navbar-inverse",
    'bootswatch_theme': "flatly",
    'globaltoc_depth': 2,
}
html_last_updated_fmt = ''
html_sidebars = {'**': ['localtoc.html','globaltoc.html','relations.html', 'sourcelink.html', 'searchbox.html']}


# Fontpath for blockdiag (truetype font)
blockdiag_fontpath = ['../../fonts/ipaexg.ttf','../../fonts/ipaexm.ttf']
seqdiag_fontpath = ['../../fonts/ipaexg.ttf','../../fonts/ipaexm.ttf']
actdiag_fontpath = ['../../fonts/ipaexg.ttf','../../fonts/ipaexm.ttf']
nwdiag_fontpath = ['../../fonts/ipaexg.ttf','../../fonts/ipaexm.ttf']

# plantuml execution path
plantuml = 'java -jar ~/Applications/plantuml/plantuml.jar'

rstドキュメント作成・編集

Sphinxプロジェクト作成により、サイトのトップページとなるマスターファイルindex.rstがsourceディレクトリ下に作成される。

toctreeディレクティブにコンテンツファイル名(拡張子無し)を追加する。toctreeはいわゆる目次となる。

.. sphinx documentation master file, created by
   sphinx-quickstart on Tue Aug  6 23:26:24 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to sphinx's documentation!
==================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   00_setup
   01_create_conf.py_t


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

その他のコンテンツとなる諸々のrstファイルを作成したり編集したりする。

Sphinxビルド

htmlをビルドする

cd ~/Documents/XDOCS/conohaVps_2019 && ls -la && pwd
make html

実行結果

(XDOCS) bash-3.2$ make html
Sphinx v2.1.2 を実行中
翻訳カタログをロードしています [ja]... 完了
出力先ディレクトリを作成しています... 完了
https://docs.python.org/objects.inv から intersphinx インベントリをロード中...
intersphinx インベントリは移動しました: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
ビルド中 [mo]: 更新された 0 件のpoファイル
ビルド中 [html]: 更新された 3 件のソースファイル
環境データを更新中3 件追加, 0 件更新, 0 件削除
ソースを読み込み中...[ 33%] 00_setup
ソースを読み込み中...[ 66%] 01_maintenance
ソースを読み込み中...[100%] index
更新されたファイルを探しています... 見つかりませんでした
環境データを保存中... 完了
整合性をチェック中... 完了
preparing documents... 完了
出力中...[ 33%] 00_setup
出力中...[ 66%] 01_maintenance
出力中...[100%] index
索引を生成中... genindex
追加のページを出力中... search
静的ファイルをコピー中... 完了
extraファイルをコピー中...完了
Japanese (code: ja) の検索インデックスを出力...完了
オブジェクト インベントリを出力...完了
ビルド 成功.

HTMLページはbuild/htmlにあります。

(XDOCS) bash-3.2$ tree
.
├── Makefile
├── build
│   ├── doctrees
│   │   ├── 00_setup.doctree
│   │   ├── 01_maintenance.doctree
│   │   ├── environment.pickle
│   │   └── index.doctree
│   └── html
│       ├── 00_setup.html
│       ├── 01_maintenance.html
│       ├── _sources
│       │   ├── 00_setup.rst.txt
│       │   ├── 01_maintenance.rst.txt
│       │   └── index.rst.txt
│       ├── _static
│       │   ├── alabaster.css
│       │   ├── basic.css
│       │   ├── bootstrap-2.3.2
│       │   │   ├── css
│       │   │   │   ├── bootstrap-responsive.css
│       │   │   │   ├── bootstrap-responsive.min.css
│       │   │   │   ├── bootstrap.css
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── img
│       │   │   │   ├── glyphicons-halflings-white.png
│       │   │   │   └── glyphicons-halflings.png
│       │   │   └── js
│       │   │       ├── bootstrap.js
│       │   │       └── bootstrap.min.js
│       │   ├── bootstrap-3.3.7
│       │   │   ├── css
│       │   │   │   ├── bootstrap-theme.css
│       │   │   │   ├── bootstrap-theme.css.map
│       │   │   │   ├── bootstrap-theme.min.css
│       │   │   │   ├── bootstrap-theme.min.css.map
│       │   │   │   ├── bootstrap.css
│       │   │   │   ├── bootstrap.css.map
│       │   │   │   ├── bootstrap.min.css
│       │   │   │   └── bootstrap.min.css.map
│       │   │   ├── fonts
│       │   │   │   ├── glyphicons-halflings-regular.eot
│       │   │   │   ├── glyphicons-halflings-regular.svg
│       │   │   │   ├── glyphicons-halflings-regular.ttf
│       │   │   │   ├── glyphicons-halflings-regular.woff
│       │   │   │   └── glyphicons-halflings-regular.woff2
│       │   │   └── js
│       │   │       ├── bootstrap.js
│       │   │       ├── bootstrap.min.js
│       │   │       └── npm.js
│       │   ├── bootstrap-sphinx.css
│       │   ├── bootstrap-sphinx.js
│       │   ├── bootswatch-2.3.2
│       │   │   ├── amelia
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── cerulean
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── cosmo
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── cyborg
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── flatly
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── img
│       │   │   │   ├── glyphicons-halflings-white.png
│       │   │   │   └── glyphicons-halflings.png
│       │   │   ├── journal
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── readable
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── simplex
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── slate
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── spacelab
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── spruce
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── superhero
│       │   │   │   └── bootstrap.min.css
│       │   │   └── united
│       │   │       └── bootstrap.min.css
│       │   ├── bootswatch-3.3.7
│       │   │   ├── cerulean
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── cosmo
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── cyborg
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── darkly
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── flatly
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── fonts
│       │   │   │   ├── glyphicons-halflings-regular.eot
│       │   │   │   ├── glyphicons-halflings-regular.svg
│       │   │   │   ├── glyphicons-halflings-regular.ttf
│       │   │   │   ├── glyphicons-halflings-regular.woff
│       │   │   │   └── glyphicons-halflings-regular.woff2
│       │   │   ├── journal
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── lumen
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── paper
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── readable
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── sandstone
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── simplex
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── slate
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── solar
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── spacelab
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── superhero
│       │   │   │   └── bootstrap.min.css
│       │   │   ├── united
│       │   │   │   └── bootstrap.min.css
│       │   │   └── yeti
│       │   │       └── bootstrap.min.css
│       │   ├── custom.css
│       │   ├── doctools.js
│       │   ├── documentation_options.js
│       │   ├── file.png
│       │   ├── jquery-3.2.1.js
│       │   ├── jquery.js
│       │   ├── js
│       │   │   ├── jquery-1.11.0.min.js
│       │   │   └── jquery-fix.js
│       │   ├── language_data.js
│       │   ├── minus.png
│       │   ├── plus.png
│       │   ├── pygments.css
│       │   ├── searchtools.js
│       │   ├── translations.js
│       │   ├── underscore-1.3.1.js
│       │   └── underscore.js
│       ├── genindex.html
│       ├── index.html
│       ├── objects.inv
│       ├── search.html
│       └── searchindex.js
└── source
    ├── 00_setup.rst
    ├── 01_maintenance.rst
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

51 directories, 100 files
(XDOCS) bash-3.2$

make html と打った場合 build/html ({ビルドディレクトリ}/{ビルダー名}) のディレクトリが作成される。 また build/doctrees が作成される。

sphinx-build の場合、ビルダー名のサブディレクトリを作成しないので、make htmlの場合と同じ構成にするには、ビルドディレクトリとして build/html ({ビルドディレクトリ}/{ビルダー名}) を指定する。-d オプション無しでビルドした場合build/html/.doctrees ({ビルドディレクトリ}/.doctrees) が作成される

sphinx-build -b html source build/html

make と同じにするにはこんな風か?

sphinx-build -b html -d build/doctrees source build/html