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