たまたんのぶろぐ

たまたんが時たま言いたいことを書いてます。ジャンルはめっちゃええ加減ですwソフトやプログラムのことが多いかもしれませんが。。。。。

MarkDownをSphinx + Pandocでマニュアル化しよう(その1)

みなさんドキュメント作成に困ったことありませんか?

私はここ数年いろいろ探していたのですが、なかなかいいものが見つかりませんでした。

最近は、GitHubが使われるようになってからかは知りませんが、MarkDownが主流になってきました。しかし、ローカルで専用アプリを入れずに見られるように出来るものが少ないです。そこで、Sphinxを使用してMarkDownを活用しようと考えました。

Sphinxは、Pythonのドキュメントツールで、PDF,EPUB、HTMLなどにビルド(生成)が出来ます。また、このツールは、reStructuredText(reST)という方式で書きます。ただし、ここ最近、recommonmarkを使用すれば、MarkDownが書けるようになっています。このやり方はいろいろ調べるといっぱい出てきます。しかし、MarkDownは、CommonMarkをベースにつくられているので、GitHub等で使用されるMarkDown方式の表などを作成することが出来ません。

そこで発想を変え、MarkDownSphinxのreStructuredTextに変換してSphinxでビルドすればどうでしょうか。今回活躍するのが、Pandocです。このツールは、あらゆるマークアップ形式を別のフォーマットに変換できる優れものです。

これについては、日本語マニュアルのサイトを見ていただくとわかりやすいでしょう。

実際にするのは、


① MarkDownで書く ② PandocでMarkDownをreST変換 ③ Sphinxの目次を整形 ④ SphinxでコンパイルしPDF,EPUB、HTMLを生成

と言った感じです。

今回は、Vagrantを使用して、実際に動作するCentOS6の環境を用意してそのツールを作成する手順を書いていきます。

  1. Vagrantの設定

  2. CentOS6の構築

  3. 各種ツールのインストール

3.1. Python3のインストール

3.2. Pandocのインストール

3.3. フォントインストール

3.4. TeX Liveのインストール

3.5. Sphinxのインストール

  1. テスト

次号に続く