はじめに

Autodocとは、rspecを実行した時にドキュメントを生成してくれるツール。

GitHubのWikiを使って画面項目やアクション、使用しているAPIについて簡単にまとめたドキュメントを作成しているプロジェクトがある。最初はAutodocで生成したドキュメントをコピペでWikiの該当箇所に貼り付けていたんだけど、さすがにメンテナンス性が悪すぎるので、Autodocのドキュメントを丸ごとWikiのリポジトリに追加してWiki内でリンクを貼って参照できるようにしようとしたところ以下のような問題が発生した。

現象

Wikiのリポジトリで

/doc/api/v1/hoge/self.md
/doc/api/v1/huga/self.md

このようなフォルダ構成にしてもGitHubのWiki画面では認識されずhttps://github.com/user-name/project-name/wiki/self となってしまってどちらか片方しか参照できない。

対策

Autodocで以下の設定を追加した。

# spec/support/autodoc.rb
Autodoc.configuration.document_path_from_example = -> (example) do
  example.file_path.gsub(%r<\./spec/[^/]+/(.+)_spec\.rb>, '\1.md').gsub(%r</>, '-')
end

こうすることで

api-v1-hoge-self.md
api-v1-huga-self.md

となりGitHubのWiki画面でそれぞれ参照できるようになった。