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

[Trac/Redmine+Subversion+Jenkinsなどを捨ててGitLabに移行するまでの道のり](https://qiita.com/hkato/items/3ddfe72985f7536bdf97)

つづき

## TL;DR

[Tracboat](https://github.com/tracboat/tracboat) の Wiki 変換 `trac2down.py` を利用し、 [MkDocs](https://www.mkdocs.org) 形式の Markdown に変換するツールを作って移行した。

https://github.com/hkato/trac2mkdocs

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

## Wiki の移行先は Wiki か Pages か？

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

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

Pages で静的な Web サイトにするにはいろいろなツールがあるかと思うが、自分が一番使い慣れた [MkDocs](https://www.mkdocs.org)を利用することとした。[Trac の Wiki](https://trac.edgewall.org/wiki/TracWiki) から各ページを Markdown に変換し、内部リンクやサイト構成を MkDocs の形式にしてあげることで、[GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) として公開できるようにした。動作確認はしていないが、 Trac Wiki から [GitHub Pages](https://docs.github.com/ja/github/working-with-github-pages/about-github-pages) への移行ツールとしても使えるはず（確認する項目でもないが）。

## 使い方

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

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

```sh
$ mkdir myproj
$ cd myproj
$ git init
```

あるいは Trac + [SubversionからGitに移行したプロジェクト](https://qiita.com/hkato/items/1b092bff149b13f77505) で `docs` のないもの場合  clone する。

```sh
$ git clone my_project_url/myproj.git
$ cd myproj
```

SubversionからGitに移行した場合すでに[git-svnで利用したマッピングファイル](https://git-scm.com/book/ja/v2/Gitとその他のシステムの連携-Git-へ移行する)があると思うので、これを `authors.txt` として事前に配置しておく。このファイルがない場合は Trac の SQLite3 データベースからユーザー情報を引っ張ってきて雛形を作るようにしたのでこれを編集。

```sh
$ trac2mkdocs /var/lib/trac/myproj
Edit ./authors.txt file before converting.
```
```text
trac = Mr. Boo <boo@example.com>
boo = Mr. Boo <boo@example.com>
taro = Trao Yamada <yamada@example.com>
```

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

```sh
$ 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
.
.
.
$ 
```
```sh
$ git log
```
```sh
commit 994d642677300219afd48612a76b518b26b6d013
Author: Mr. Boo <boo@example.com>
Date:   Wed Jan 16 14:44:53 2013 +0000

    Upload attachment

commit 45bcaa6bce70fbe0acb5693eed4fcb7818bdc734
Author: Mr. Boo <boo@example.com>
Date:   Wed Jan 16 14:40:03 2013 +0000

    Update version 2

commit e4e5434f25ea54c2aeb19b977d056a656b5fcb75
Author: Mr. Boo <boo@example.com>
Date:   Thu Jan 10 09:06:38 2013 +0000

    Add version 1
```

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

```yml
site_name: Convert from Trac Wiki
theme: readthedocs
```

テストサーバを起動し、

```sh
$ mkdocs serve
```

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

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

### MkDocs のカスタマイズ

- [MkDocsによるドキュメント作成](https://qiita.com/mebiusbox2/items/a61d42878266af969e3c)

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

### GitLab CI での Pages 化

- [Example MkDocs website using GitLab Pages.](https://gitlab.com/pages/mkdocs)

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

## MkDocs 化と Tracboat と異なるところ

### リンク

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

```markdown
[[MyWikiPage]]
```

これを、

```markdown
[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に関する説明が初期ページ](https://trac.edgewall.org/wiki/WikiFormatting)として作成される。これらは Markdown/MkDocs 化したときに不要なものなので対象外として変換しないこととした。また`WikiStart`がトップページになるので、これだけは`index.md`として変換し、MkDocsから見た時にトップページになるようにした。Trac Wiki 上で `WikiStart` 以外の初期ページを編集した場合（あまりないと思うが）は注意。

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

## TODO

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