secretbase.log

.NET/C#/Pythonなど

pandoc で Redmine の Wiki を Sphinx に変換しよう

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に変換してみましょう。ひとまず対象は1ページです。

結果をおみせします。

変換前: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

オプション(今回使ったもの。一部)

-f FORMAT 入力フォーマット指定(from)
-t FORMAT 出力フォーマット指定(to)

さいごに

いかがでしたでしょうか。様々な形式のファイルをreSTに変換し、充実のSphinxライフを始めるのもいいと思います。
明日は、 @ さんです。今年私がSphinxを始めた時の先生でした。素晴らしいエントリになること間違いないでしょう。よろしくお願いします。

*1:redmineのWikiページから生のtextileをhttp経由で引っ張ってこれれば少し楽ですがやり方が見つかりませんでした