意識の高いLISPマシン

藤原惟/すかいゆき(@sky_y)の技術用ブログ

MarkdownでSphinxできるようになったので試してみた(後編)

この記事はドキュメンテーションツールAdvent Calendar (http://www.adventar.org/calendars/1196) の2日目です。

(まだまだ空欄だらけなので、執筆者も募集しています。)

この記事は2部構成の2部目です。

今回は、実際にSphinxをインストールし、Markdownで文書が作成できるかどうかを試してみます。

なお、元ネタはこのプレゼンです(再掲)。

準備

Mac OS X上で作業。HomebrewでインストールしたPython2を使用します。

最近ターミナルをほったらかしていたので、まずHomebrewを整備します。

$ brew doctor
$ brew update
$ brew upgrade

バージョンを確認。

$ python --version
Python 2.7.10

インストールしてみる

Sphinxの最初の一歩 — Sphinx 1.3.2 ドキュメント を元にインストールしてみます。

Sphinxをインストール。

pip install Sphinx commonmark recommonmark

次はsphinx-quickstartですが、そのままだとエラーになります。

sphinx で ValueError: unknown locale: UTF-8 というエラーが出た - Please Sleep

エラーを修正するために、.bashrcまたは.zshrcに下記を追加し、シェルを再起動します。

export LC_ALL='ja_JP.UTF-8'

文書を書いてみる

まず、ターミナルを開き、適当なディレクトリを作ります。これを作業ディレクトリにします。

続いて、sphinx-quickstartを実行します。ここから対話形式で質問されるので、下記のように答えました。(わかる人は好みで変えてもOKです。)

 $ sphinx-quickstart                                                                                                                          [2:43:20]
Welcome to the Sphinx 1.3.2 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 [.]: 【何も記入せずEnter】

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]: y

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 [_]: 【何も記入せずEnter】

The project name will occur in several places in the built documentation.
> Project name: trial 【好きな名前にする】
> Author name(s): sky_y 【好きな名前にする】

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: 0.1
> Project release [0.1]: 【何も記入せずEnter】

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]: ja

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]: 【何も記入せずEnter】

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]: 【何も記入せずEnter】

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [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]: 【何も記入せずEnter】
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: 【何も記入せずEnter】
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: 【何も記入せずEnter】
> coverage: checks for documentation coverage (y/n) [n]: 【何も記入せずEnter】
> pngmath: include math, rendered as PNG images (y/n) [n]: 【何も記入せずEnter】
> 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]: 【何も記入せずEnter】
> viewcode: include links to the source code of documented Python objects (y/n) [n]: 【何も記入せずEnter】

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-build
directly.
> Create Makefile? (y/n) [y]: 【何も記入せずEnter】
> Create Windows command file? (y/n) [y]: n

Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.

Finished: An initial directory structure has been created.

You should now populate your master file ./source/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.

source/conf.pyを修正する

ここでカレントディレクトリを見ると、buildsourceの二つのディレクトリが出来ています。

 $ ls
Makefile  build/    source/

Markdownを使用するにはsource/conf.pyをいじる必要があるので、下記のように変更します:

-source_suffix = ['.rst']
+source_suffix = ['.rst', '.md']
+source_parsers = {
+    '.md' : 'recommonmark.parser.CommonMarkParser'
+}

ドキュメント構造を定義する

Sphinxではsource/index.rstに必要なファイルの名前を追加することで、 構造を明示的に指定する必要があります。

ここでは、main.mdというファイルを追加するつもりで、source/index.rstを下記のように変更します(空行に注意):

Contents:

.. toctree::
   :maxdepth: 2

   main              ←これを追加する(拡張子は不要)

Markdown文書を作る

sourceディレクトリの下に、main.mdというMarkdown文書を適当に作ります。 例えばこんな感じ:

# Markdownを使ったドキュメント

これはMarkdownを使ったドキュメントです。

## 例えば

* リストは
* こんな感じです。

ビルドする

最後にビルドします。この設定ではmakeコマンドが使えます。引数には形式を指定するのですが、指定できる形式は引数無しでmakeを打つと見ることができます。

ここではHTMLを生成してみます。

make html

すると、build/htmlの下にHTML文書一式が現れます。

結果

ターミナルでopen build/html/index.htmlと打つと、そのままブラウザで閲覧できます。 面倒なのでスクリーンショットだけ示します。

indexページ(index.rst)。

f:id:sky-y:20151201032520p:plain

Markdownで書かれたmainページ(main.md)。

f:id:sky-y:20151201032529p:plain

使えるMarkdown書式

基本的にはCommonMarkで使えるものしか使えません。 下記を参照してください。

CommonMark Spec

まとめ

SphinxでうまくMarkdown文書を取り込めました。

Sphinxを使ったのは初めてですが、なかなか奥の深さを感じさせられるツールです。 もう少し深掘りしてみたいです。

なお、類似ツールにPandocがあるのですが、比較すると

  • Pandoc: 単一ページの変換向け、多種多様なフォーマットで入出力できる
  • Sphinx: 複数ページから成る一式の文書(HTML, PDF, LaTeX)向け

のように思います。適材適所で使えたらよいかと思います。

最後に、Sphinx-usersメーリングリストの方々に感謝の意を示して、この記事を終わります。