RustリポジトリのREADME.mdメンテナンスを自動化する

はじめに

GitHubのREADME.mdはついついアップデートを忘れてしまって、ソースコードとの不一致を起こしてしまいます。
今回は以下の2点について自動化してみました。

• [dependencies]のバージョン表記
• サンプルソースのテスト

実際に適用したリポジトリはこちらです。

[dependencies]のバージョン表記

ここで言うバージョン表記とはRustライブラリのUsageによくある

[dependencies]
fts = "0.1.7"

というやつです。
まあcrates.ioを見に行けば書いてあるのですが、ないと寂しいのでついつい書いてしまいます。

この更新を自動化するにはcargo releaseを使います。
これはcargo publishに関連する作業を自動化するツールで、Cargo.tomlのversion書き換えやgitのタグ付け、cargo publishまでを自動でやってくれます。
このツールはREADME.mdの書き換えを想定した機能も入っており、Cargo.tomlに以下のように設定します。

[package.metadata.release]
pre-release-replacements = [
    { file = "README.md", search = "fts = \"[a-z0-9\\.-]+\"", replace = "fts = \"{{version}}\"" },
]

これによりfileから正規表現searchにマッチする部分をreplaceに置き換えてくれます。
{{version}}はリリースしようとしているバージョンに置き換わります。

サンプルソースのテスト

Rustではソースコード中のコメントはテストできますが、README.mdのサンプルソースは対象外です。
cargoのPRにはずいぶん前から上がっていますが特に入る予定もなさそうです。
というわけでrust-skepticを使います。
カスタムビルドスクリプトを使っているので結構手順が多いですが以下のように使います。
（コードブロック内で```を書く方法が分からなかったので一部`` `としています）

• Cargo.tomlに追記

[package]
build = "build.rs"

[build-dependencies]
skeptic = "0.13"

[dev-dependencies]
skeptic = "0.13"

• build.rsを追加

extern crate skeptic;

fn main() {
    skeptic::generate_doc_tests(&["README.md"]);
}

• tests/skeptic.rsを追加

include!(concat!(env!("OUT_DIR"), "/skeptic-tests.rs"));

• （必要に応じて）README.md.skt.mdを追加

```rust,skt-default
extern crate fts;

fn main() {{
    {}
}}
`` `

• README.mdのソースコード

```rust,skt-default
use std::path::Path;
use fts::walkdir::{WalkDir, WalkDirConf};

let path = Path::new( "." );
for p in WalkDir::new( WalkDirConf::new( path ) ) {
    println!( "{:?}", p.unwrap() );
}
`` `

README.md.skt.mdはREADME.mdのソースコードがfn main()を含まない場合など、そのままではコンパイルできないときに使います。
README.mdのコードブロックで ```rust, テンプレート名 と指定すれば、README.md.skt.mdの同じ名前のコードブロックの{}に埋め込んだ形でコンパイルしてくれます。

実行時の流れは以下のようになっています。

• build.rsがREADME.mdからRustのコードブロックを抜き出してskeptic-tests.rsを生成
• tests/skeptic.rsが生成されたskeptic-tests.rsをincludeしているので、これを普通にテスト

何かうまくいかない時は以下で実行しようとしているソースコードを確認するといいでしょう。

$ cat ./target/debug/build/*/out/skeptic-tests.rs