Trac WikiをMkDocs形式のMarkdownに変換する

Trac/Redmine+Subversion+Jenkinsなどを捨ててGitLabに移行するまでの道のり

つづき

TL;DR

Tracboat の Wiki 変換 trac2down.py を利用し、 MkDocs 形式の Markdown に変換するツールを作って移行した。

英文ドキュメントやテストを用意してないので、まだ PyPI には置いてないが、ここらへんを追加したら置くかもしれない。

Wiki の移行先は Wiki か Pages か？

GitLab や GitHub にも Wiki 機能はあるが、Markdownドキュメントをソースとして管理し静的なページに変換する Pages 機能とかぶる気もする。

自分は、 GitLab の Wiki を使うこともあるが、どちらかというと自分は Pages 派。特に過去プロジェクトを掘り起こしての移行が中心なので、あまり編集もすることはないし Pages として変換することとした。(探してみた既存の変換ツールがうまく動かなかったというのもある)

Pages で静的な Web サイトにするにはいろいろなツールがあるかと思うが、自分が一番使い慣れた MkDocsを利用することとした。Trac の Wiki から各ページを Markdown に変換し、内部リンクやサイト構成を MkDocs の形式にしてあげることで、GitLab Pages として公開できるようにした。動作確認はしていないが、 Trac Wiki から GitHub Pages への移行ツールとしても使えるはず（確認する項目でもないが）。

使い方

$ pip install git+https://github.com/hkato/trac2mkdocs.git

移行先の適当なディレクトリを初期化して、

$ mkdir myproj
$ cd myproj
$ git init

あるいは Trac + SubversionからGitに移行したプロジェクト で docs のないもの場合 clone する。

$ git clone my_project_url/myproj.git
$ cd myproj

SubversionからGitに移行した場合すでにgit-svnで利用したマッピングファイルがあると思うので、これを authors.txt として事前に配置しておく。このファイルがない場合は Trac の SQLite3 データベースからユーザー情報を引っ張ってきて雛形を作るようにしたのでこれを編集。

$ trac2mkdocs /var/lib/trac/myproj
Edit ./authors.txt file before converting.

trac = Mr. Boo <[e-mail]>
boo = Mr. Boo <[e-mail]>
taro = Trao Yamada <[e-mail]>

再度実行すると、 Trac+SQLite3 database から Wiki や添付ファイルを引き出し、MkDocs の形式の Markdown と そのファイル郡を Git として commit していく。

$ trac2mkdocs /var/lib/trac/myproj
2013-01-10 09:06:38 trac index Add version 1
2013-01-16 14:40:03 boo index Update version 2
2013-01-16 15:22:14 boo test.jpeg Upload attachment
2013-01-16 17:09:56 boo index Update version 3
2013-01-25 15:51:11 boo index Update version 4
.
.
.
$ 

$ git log

commit 994d642677300219afd48612a76b518b26b6d013
Author: Mr. Boo <[e-mail]>
Date:   Wed Jan 16 14:44:53 2013 +0000

    Upload attachment

commit 45bcaa6bce70fbe0acb5693eed4fcb7818bdc734
Author: Mr. Boo <[e-mail]>
Date:   Wed Jan 16 14:40:03 2013 +0000

    Update version 2

commit e4e5434f25ea54c2aeb19b977d056a656b5fcb75
Author: Mr. Boo <[e-mail]>
Date:   Thu Jan 10 09:06:38 2013 +0000

    Add version 1

変換が完了したら、とりあえずシンプルな mkdocs.yml でも用意し、

site_name: Convert from Trac Wiki
theme: readthedocs

テストサーバを起動し、

$ mkdocs serve

http://localhost:8000 にブラウザでアクセスすると Trac Wiki が Markdown に変換されたものが表示される。上記 mkdocs.yml の設定だとRead the DocsのテーマでHTML化されたものになる。

docs は commit 済みなので、mkdocs.yml を必要に応じてカスタマイズし、add & commit し remote に push すれば移行完了。

MkDocs のカスタマイズ

• MkDocsによるドキュメント作成

などを参照してフォントとか色をカスタマイズ。

GitLab CI での Pages 化

• Example MkDocs website using GitLab Pages.

ここらへんの .gitlab-ci.yml が参考になるかと。

MkDocs 化と Tracboat と異なるところ

リンク

Tracboat の変換だとローカルのリンクは次のようになる

[[MyWikiPage]]

これを、

[MyWikiPage](../MyWikiPage)

となるように変換した。MkDocsは

docs/
    index.md
    MyWikiPage.md
    HogePage.md
    HagePage.md

の場合HTMLに変換した場合のURLは
http://localhost:8000/MyWikiPage/となるのでローカルドキュメント間のリンクの整合性がとれる。

添付ファイルパス

Tracboatは

/uploads/migrated/hoge.jpeg

となる。Wiki に 画像以外のファイルをアップロードすることもあるとは思うが、自分の利用方法の場合、画像が中心だったことと、上記のように絶対パスだったので、docs/images/hoge.jpegに吐き出すことにより、URLは http://localhost/images/hoge.jpeg で Markdown ページからの相対パスになり、Pages化しても整合性がとれるようにした。

変換対象外ページ

Tracインストールしプロジェクトを初期化した時にはTracAdmin,TracGuideなどのTracの説明やWikiFormattingなどのWikiに関する説明が初期ページとして作成される。これらは Markdown/MkDocs 化したときに不要なものなので対象外として変換しないこととした。またWikiStartがトップページになるので、これだけはindex.mdとして変換し、MkDocsから見た時にトップページになるようにした。Trac Wiki 上で WikiStart 以外の初期ページを編集した場合（あまりないと思うが）は注意。

その他、tracboat/trac2down.py はいじっていないので、いまいち変換がうまく行かがい Wiki記法はオリジナルの制限通り。

TODO

• 最初に書いたとおり英文ドキュメントとテストを追加したら、PyPI に上げるかも。
• 残るは Redmine Wiki → Pages 変換かなぁ？