注意
計算機のことに詳しくないので素人的に変な言い回しをしているかもしれない。気づいたらコメントなどで教えていただけたら嬉しい。
introduction
私は、Pythonを利用してプログラムを書く際にはpydoc形式のコメントを書いている。ならばそれをまとめたような簡易的なドキュメントを作っておきたい。イメージとしては下記のようなものである。
開発自体はPycharmを利用していることが多いので、Pycharmからドキュメントを生成する際のメモを残しておくことにした。
トップページ
APIのことがあれこれ記述されている
コードにも飛べる
setting
使用したコード、Pycharmは以下の通り
- 利用コード
- 今回利用したコードはhttps://github.com/aomidro/BayesianOptimizer にあるベイズ最適化の練習コード。コードから著書の力量の低さがうかがえる。
Pycharmを利用してこのコードを書いているとして、これに関するドキュメントをSphinxで生成したい。
- Pycharmのバージョン
- Pycharm Community Edition 2016.1.4
- Build #PC-145.1504 built on May 25, 2016
方法
introductionに書かれたようなものを作るための手順は以下の通り。以下にこの手順にそった場合の手続きを書いておく。
- Pycharmで何かのプロジェクトを開く
- Sphinxの初期設定を行う
- Sphinx QuickStartによる全体的な初期設定
- conf.pyの書き換え
- sphinx-apidocでmodule関係の記述をしたrstファイルを作成する
- makeする
1.Pycahrmで何かのプロジェクトを開く
説明不要かもしれない。githubから引っ張ってきた上述のコードの場合、下記のような状態になっていると思う。
2.Sphinxの初期設定を行う
Sphinx QuickStartによる全体的な初期設定
Pycharmの"Tools"からSphinx Quickstartを押す。ここで、プロジェクト名は何にするかであるとか、pydocからの自動生成はするのかといったようなことを設定する。押すと、Pycharmの画面下方にコンソールが出てきて、そこで対話的にやりとりをする。下記のようなやりとりをする。意味を取り間違える箇所は殆ど無いと思うのだけれど、autodocの件は'y'と答えておかないとあとで手で設定ファイルを直さなくちゃいけない。
Welcome to the Sphinx 1.3.5 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]:
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
The project name will occur in several places in the built documentation.
> Project name: test project
> Author name(s): ########
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]: 1.0.0
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]:
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]:
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]:
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> pngmath: include math, rendered as PNG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx:helmet_with_cross:-build
directly.
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]: n
Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.
Finished: An initial directory structure has been created.
conf.pyの書き換え
autodocなどの機能は拡張機能なのだが、それらのファイルは大抵プロジェクトディレクトリにはない。
その場合には、下記のようにしてやる。
# 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.
sys.path.insert(0, os.path.abspath('.'))
3. sphinx-apidocでmodule関係の記述をしたrstファイルを作成する
ターミナルから、sphinx-apidocを叩く。使い方は下記のとおりである。
sphinx-apidoc -f -o (生成物を置きたいディレクトリ) （ソースコードが入っているディレクトリ）
-fで上書きを許容して、-oでアウトプットディレクトリを指定する。成功すると、modules.rstなどができているはずである。
さらに、トップページから飛べるように、おそらくすでに作成されているであろうindex.rstファイルを以下のように編集する。
Welcome to test project's documentation!
========================================
Contents:
.. toctree::
:maxdepth: 2
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
4. makeする。
ターミナルからなら、sphinx-apidocを叩いたのと同じ場所で、
make html
すればよい。pycharmからであれば、runから実行できる。Run->Edit Configurationsで、下記のような感じで設定する。
こうすると、_build以下に一式が置かれることになる。