概要

遅まきながら、sphinx使えるようになりたいって事で

まずは勉強用の環境を構築する際のメモ。たぶんその内忘れてしまいそうなので。

環境は mac ですが、windows でもだいだい同じでした。

毎回 make html するのが面倒なので、エディタでプレビューもさせたい。

Sphinxって何？

概要 — Sphinx 1.5.6 ドキュメント

sphinx-users.jp

Home | Read the Docs

ブロック図生成ツール blockdiag — blockdiag 1.0 ドキュメント

前提条件

私の環境には、Anaconda がインストールされています。

なので、最初から sphinx はインストール済みでした。

準備

必要なライブラリを pip でインストール

$ pip install restructuredtext-lint
$ pip install sphinx-autobuild
$ pip install sphinx_rtd_theme

vs code で reStructuredText プラグインをインストール

github.com

初めての 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('.'))

の部分のコメントを外して、調整すればいけるみたいですね。

とりあえず、今回はここまで。

過去の記事については、以下のページからご参照下さい。