かわろぐ

技術、セキュリティ、その他もろもろ

MENU

Sphinx で Markdown を使えるようにする

前回前々回とエンジニア向けのドキュメントを作る話をしていて、gitbook を使ってみましたが、なんとメンテナンスされていないという自体が発覚しました。最初からちゃんと調べろよという感じですが。。。

そこで Python 界隈でよく使われている Sphinx に狙いを定めました。最初は markdown でないマークアップ言語しか使えないと思っており、敬遠していましたが、プラグインを入れることでMarkdownでもドキュメントがかけるようになっているとのことで改めて調査しました。

今回は Sphinx の環境セットアップとMarkdownでサンプルドキュメントを作るところまでをやってみたいと思います。

環境

  • MacOSX
  • Homebrew

Sphinx をインストールする

Python は Homebrew を使って pyenv をインストールしてあるものと仮定します。 

pip install -U Shinx

クイックスタートでひな形を作る

Sphinx には初期に必要なファイルを自動で生成してくれるツールがあります。 専用に作ったディレクトリの中で、 sphinx-quickstart と打ってみると、設定項目をいくつか聞かれた後に、いくつかのファイルやディレクトリが作成されます。

$ sphinx-quickstart
Sphinx 2.2.1 クイックスタートユーティリティへようこそ。

以下の設定値を入力してください(Enter キーのみ押した場合、
かっこで囲まれた値をデフォルト値として受け入れます)。

選択されたルートパス: .

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける(y / n) [n]:

プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
> プロジェクト名: test
> 著者名(複数可): kawa
> プロジェクトのリリース []:

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
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> プロジェクトの言語 [en]: ja

ファイル ./conf.py を作成しています。
ファイル ./index.rst を作成しています。
ファイル ./Makefile を作成しています。
ファイル ./make.bat を作成しています。

終了:初期ディレクトリ構造が作成されました。

マスターファイル ./index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
 make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。

Markdown 用のプラグインをインストールし、使えるようにする

次に Sphinx で Markdown を使えるようにプラグインを一つインストールします。

pip install recommonmark

インストールが完了したら、先程のquickstart で作った conf.py に以下のように追記します。 Extention 自体は記載があるはずなので、 recommonmark の部分を追記すればOKです。

extensions = [
    'recommonmark'
]

Markdownファイルを Sphinx に認識させるために拡張子と、使うパーサーを同じ設定ファイルに書きます。

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

Recommonmark は table に対応していないようなので sphinx-markdown-tables をインストールします。

pip install sphinx-markdown-tables

Recommonmark と同じく、 extentions に名前を書きます。

Markdown ファイルを作って html で表示してみる

プロジェクトのルートディレクトリにある、 index.rst ファイルは削除してください。このファイルが残っていると、markdown ファイルを指定してもこちらが優先されてしまいます。

今回はサンプルとして以下のようなドキュメントを用意しました。

index.md

# hello sphinx!
スフィンクスで書く最初のドキュメントです。

ビルドし、HTMLファイルを生成するのは以下のコマンドです。

$ sphinx-build . out index.md 

これで out ディレクトリの中に html ファイルが生成されているので、適当なブラウザで表示してみてください。

次回はPDFファイルに出力できる用にしてみたいと思います。

参考文献

https://sphinx-users.jp/gettingstarted/index.htmlhttps://qiita.com/it__ssei/items/2a1205cfd3ac3ee61a57https://qiita.com/unhurried/items/f0372688e8a8485718b5