概要
遅まきながら、sphinx使えるようになりたいって事で
まずは勉強用の環境を構築する際のメモ。たぶんその内忘れてしまいそうなので。
環境は mac ですが、windows でもだいだい同じでした。
毎回 make html するのが面倒なので、エディタでプレビューもさせたい。
Sphinxって何？
ブロック図生成ツール blockdiag — blockdiag 1.0 ドキュメント
前提条件
私の環境には、Anaconda がインストールされています。
なので、最初から sphinx はインストール済みでした。
準備
必要なライブラリを pip でインストール
$ pip install restructuredtext-lint $ pip install sphinx-autobuild $ pip install sphinx_rtd_theme
vs code で reStructuredText プラグインをインストール
初めての sphinx 環境構築
sphinx-quickstart 実行
$ sphinx-quickstart
いろいろ聞かれますが、今回は
- Root path for the documentation [.]: try-sphinx
- Project name: try-sphinx
- Project language [en]: ja
- autodoc: automatically insert docstrings from modules (y/n) [n]: y
- doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
- Create Makefile? (y/n) [y]: y
- Create Windows command file? (y/n) [y]: y
ってところは選んで、後は適当に入れました。
すると
Creating file try-sphinx/conf.py. Creating file try-sphinx/index.rst. Creating file try-sphinx/Makefile. Creating file try-sphinx/make.bat. Finished: An initial directory structure has been created. You should now populate your master file try-sphinx/index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
って出たので
$ cd try-sphinx
$ make
ってすると
Sphinx v1.6.3 Please use `make target' where target is one of html to make standalone HTML files dirhtml to make HTML files named index.html in directories singlehtml to make a single large HTML file pickle to make pickle files json to make JSON files htmlhelp to make HTML files and an HTML help project qthelp to make HTML files and a qthelp project devhelp to make HTML files and a Devhelp project epub to make an epub latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter latexpdf to make LaTeX and PDF files (default pdflatex) latexpdfja to make LaTeX files and run them through platex/dvipdfmx text to make text files man to make manual pages texinfo to make Texinfo files info to make Texinfo files and run them through makeinfo gettext to make PO message catalogs changes to make an overview of all changed/added/deprecated items xml to make Docutils-native XML files pseudoxml to make pseudoxml-XML files for display purposes linkcheck to check all external links for integrity doctest to run all doctests embedded in the documentation (if enabled) coverage to run coverage check of the documentation (if enabled)
って出た。なるほど、html 作りたい場合は make html ってするのね。
てことで
$ make html
ってすると
Running Sphinx v1.6.3 making output directory... loading translations [ja]... done loading pickled environment... not yet created building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in Japanese (code: ja) ... done dumping object inventory... done build succeeded. Build finished. The HTML pages are in _build/html.
って出た。ちゃんと出来たみたい。 html出来たみたいなので
$ open _build/html/index.html
ってしたら、表示された :)
vs code で markdown みたいにプレビュー出来るようにする
毎回、make html って打つのも面倒なので、プレビュー出来るように調整。
先にインストールしておいた reStructuredText プラグインの設定をする。
$ code .
で vs code を起動して
> Open Workspace Settings
で, ワークスペース設定を作る。
以下の設定を追加。/path/to/sphinx-build の部分は which sphinx-build の結果を入れる。
{ "restructuredtext.builtDocumentationPath": "${workspaceRoot}/_build/html", "restructuredtext.confPath": "${workspaceRoot}", "restructuredtext.updateOnTextChanged": "false", "restructuredtext.sphinxBuildPath": "/path/to/sphinx-build", "restructuredtext.linter.executablePath": "restructuredtext-lint", "restructuredtext.linter.sphinxDirectives": ["toctree"], "restructuredtext.linter.sphinxTextRoles": ["doc","ref"] }
ほぼデフォルトの状態だけど、とりあえず設定項目として記載しておいた。
おそらく、実際ちゃんとやるときは ルートディレクトリの直下に _build とか
つくらずに、ちゃんと docs みたいなディレクトリ作ると思うので。
この後、index.rst を開いた状態で
> reStructuredText: Toggle Preview
ってやると、プレビューが表示できた :)
conf.py 調整
とりあえず、表示は出来たけど、ReadTheDocs みたいな感じじゃなくてハゲシクダサい。。
ってことで、テーマを変更。conf.py を開いて
# The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'alabaster'
って部分を
# The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme'
に変更。再度、プレビューするとちゃんと ReadTheDocsみたいになった :)
python の api ドキュメント自動生成とかする場合は
# If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # # import os # import sys # sys.path.insert(0, os.path.abspath('.'))
の部分のコメントを外して、調整すればいけるみたいですね。
とりあえず、今回はここまで。
過去の記事については、以下のページからご参照下さい。
- いろいろ備忘録日記まとめ
サンプルコードは、以下の場所で公開しています。
- いろいろ備忘録日記サンプルソース置き場
