mise.tomlのタスク一覧をドキュメント化したい
mise.tomlにタスクを増やしていくと、README等に手動でタスクの説明を書き足すのは手間になる。mise generate task-docsは、タスクのdescriptionやusageからMarkdown形式のドキュメントを自動生成するコマンドである。
基本の使い方
引数なしで実行すると、標準出力にMarkdown形式でタスク一覧を出力する。
[tasks.build]
description = "Build the project"
run = "echo build"
[tasks.test]
description = "Run tests"
run = "echo test"
usage = '''
arg "target" default="all" "Test target to run"
'''
$ mise generate task-docs
## `build`
- **Usage:** `build`
Build the project
## `test`
Run tests
- **Usage:** `test [target]`
### Arguments
- **`[target]`**
**Default:** `all`
descriptionはタスクの説明として、usageで定義した引数は### Argumentsとして、それぞれ自動的にドキュメントへ反映される。
hideされたタスクは出力されない
hide = trueを設定したタスクは、ドキュメント生成の対象から除外される。内部用のタスクをドキュメントから省きたい場合に使える。
–injectで既存ファイルに埋め込む
--injectと-o(出力先ファイル)を組み合わせると、既存のMarkdownファイルの決まった位置にタスク一覧を埋め込める。埋め込み先には<!-- mise-tasks -->と<!-- /mise-tasks -->という2つのコメントを事前に用意しておく必要がある。
# My Project
Some intro text.
<!-- mise-tasks -->
old content here
<!-- /mise-tasks -->
More text after.
$ mise generate task-docs --inject -o README.md
Wrote to README.md
実行すると、2つのコメントの間だけが生成したタスク一覧に置き換わり、それ以外の部分はそのまま残る。この仕組みにより、同じコマンドを繰り返し実行してもタスク一覧の部分だけを更新できる。2つのコメントが両方とも存在しない場合はエラーになり、ファイルは書き換えられない。
–multi/–indexで複数ファイルに分割する
--multiを付けると、タスクごとに個別のMarkdownファイルへ分割して出力する。出力先はディレクトリを-oで指定するが、そのディレクトリはあらかじめ作成しておく必要がある。存在しないディレクトリを指定するとmise ERROR \–output` must be a directory when `–multi` is set`というエラーになる。
$ mkdir -p docs
$ mise generate task-docs --multi -o docs
Wrote to docs/build.md
Wrote to docs/test.md
タスク名に:が含まれる場合、ファイル名では-に変換される。たとえばdb:migrateというタスクはdb-migrate.mdというファイル名になる。
--indexを追加すると、各タスクファイルへのリンクをまとめた索引ファイルindex.mdも同時に生成される。
$ mkdir -p docs
$ mise generate task-docs --multi --index -o docs
Wrote to docs/build.md
Wrote to docs/test.md
Wrote to docs/index.md
# Tasks
- [build](./build.md) - Build the project
- [test](./test.md) - Run tests
--indexは--multiと組み合わせて使うためのオプションで、単体で指定しても意味を持たない。
