pandoc で Redmine の Wiki を Sphinx に変換しよう - secretbase.log

Sphinx Advent Calendar 2012 - connpass の 15日目のエントリとなります。本日は、pandocというドキュメント変換ツールの紹介です。
Sphinx を使う場合、reSTにてドキュメントを記述しますが、例えばプロジェクト管理にRedmineを導入している場合、Wikiに書きためた文章があるかと思います。RedmineのWikiは textile 記法なので、reSTにうまく変換する方法があったらいいと思いませんか？
そんな textile を reST に変換してくれるツールとして使えそうな pandoc を紹介したいと思います。

pandoc とは

pandoc は、ユニバーサルドキュメントコンバータです。
textileだけではなく、入力フォーマットとして、markdown, HTMLなどいろいろあり、出力も reST, markdown はもちろん、HTML, ePUB, PDFがあります。

pandoc のインストール

Pandoc - About pandoc からインストールできます。
Windows版も用意されており、簡単ですね

pandoc の起動

環境変数PATHが通っていますので、コマンドプロンプトから pandoc が実行できるハズです。

C:\Users\tkondou>pandoc -v
pandoc 1.9.4.2
Compiled with citeproc-hs 0.3.4, texmath 0.6.1.1, highlighting-kate 0.5.3.2.
Syntax highlighting is supported for the following languages:
    Actionscript, Ada, Alert, Alert_indent, Apache, Asn1, Asp, Awk, Bash,
    Bibtex, Boo, C, Changelog, Clojure, Cmake, Coffee, Coldfusion, Commonlisp,
    Cpp, Cs, Css, D, Diff, Djangotemplate, Doxygen, Doxygenlua, Dtd, Eiffel,
    Email, Erlang, Fortran, Fsharp, Gnuassembler, Go, Haskell, Haxe, Html, Ini,
    Java, Javadoc, Javascript, Json, Jsp, Latex, Lex, LiterateHaskell, Lua,
    Makefile, Mandoc, Matlab, Maxima, Metafont, Mips, Modula2, Modula3,
    Monobasic, Nasm, Noweb, Objectivec, Objectivecpp, Ocaml, Octave, Pascal,
    Perl, Php, Pike, Postscript, Prolog, Python, R, Relaxngcompact, Rhtml, Ruby,

    Scala, Scheme, Sci, Sed, Sgml, Sql, SqlMysql, SqlPostgresql, Tcl, Texinfo,
    Verilog, Vhdl, Xml, Xorg, Xslt, Xul, Yacc, Yaml
Copyright (C) 2006-2012 John MacFarlane
Web:  http://johnmacfarlane.net/pandoc
This is free software; see the source for copying conditions.  There is no
warranty, not even for merchantability or fitness for a particular purpose.

C:\Users\tkondou>

pandoc で、 Redmine の Wiki を Sphinx にする

redmineのwikiをsphinxに変換してみましょう。ひとまず対象は１ページです。

結果をおみせします。

変換前：https://my.redmine.jp/demo/projects/demo/wiki/Textile_test
f:id:cointoss1973:20121212172235p:plain

変換後：http://cointoss1973.bitbucket.org/pandoc-sample/_build/html/index.html
f:id:cointoss1973:20121212172245p:plain

Redmine.JP のデモサイトをお借りしましたm(__)m

code のところは、preタグの中身がそのまま変換されているので、シンタックスハイライトをしたい場合、 code-block などのdirective を使うように書き換える必要がありそうです。

今回行った手順

さすがに、pandocだけでページの更新まではできません。よって、下記のような手順をとりました。*1

Redmine の Wiki からテキストファイルとしてダウンロード
pandoc -f textile -t rst ~/Downloads/Textile_test.txt > index.rst
Sphinx でビルド

pandoc の仕様 (1.9.4.2時点)

pandocの簡単な仕様をのせておきます。詳しくはドキュメントや pandoc -h をどうぞ。

入力フォーマット

入力	native, json, markdown, markdown+lhs, rst, rst+lhs, docbook,textile, html, latex, latex+lhs
出力	native, json, html, html5, html+lhs, html5+lhs, s5, slidy, slideous, dzslides, docbook, opendocument, latex, latex+lhs, beamer, beamer+lhs, context, texinfo, man, markdown, markdown+lhs, plain, rst, rst+lhs, mediawiki, textile, rtf, org, asciidoc, odt, docx, epub