✏️

ex_docにチートシート機能が増えたので試してみる

2022/10/25に公開

Elixir

tech

ExDocのv0.29にチートシート機能が搭載されたようです。

ex_docのhexdocsに実際の例が公開されています。.cheatmd という拡張子を使ったドキュメントに対して所定のスタイルを当ててくれるようです。

試してみる

空のプロジェクトを作って試してみます。

$ mix new cheatsheet_sample

ex_docのv0.29が取得できるようにdepsを追加します。

mix.exs

  defp deps do
    [
+       {:ex_doc, "~> 0.29", only: :dev, runtime: false}
-     # {:dep_from_hexpm, "~> 0.3.0"},
-     # {:dep_from_git, git: "https://github.com/elixir-lang/my_dep.git", tag: "0.1.0"}
    ]
  end

mix.exsのproject設定にdocsの項目を追加します。

mix.exs

  def project do
    [
      app: :cheatsheet_sample,
      version: "0.1.0",
      elixir: "~> 1.14",
      start_permanent: Mix.env() == :prod,
      deps: deps(),
+     docs: [
+       main: "CheatsheetSample",
+       extras: ["README.md", "Cheatsheet.cheatmd"]
+     ]
    ]
  end

mix.exsの修正が終わったら、extrasで指定したパス（今回はプロジェクトのroot）にファイルを作成します。Cheatsheetの置き場を別のディレクトリに変えたければ、extrasの部分を docs/Cheatsheet.cheatmd のようにmdファイルのパスを変更したらOKです。

Cheatsheet.cheatmd

# Cheatsheet

## h2

### h3

#### h4

this is cheatsheet sample.

```elixir
[1, 2, 3]
|> Enum.map(& &1 * &1)
|> Enum.sum()
```

#### list sample

- a
- b
- c

#### table sample

key | value
:-- | :--
a | b
c | d

mdファイルを作成したら、mix docs コマンドでドキュメントを生成します。

$ mix docs
Generating docs...
View "html" docs at "doc/index.html"
View "epub" docs at "doc/cheatsheet_sample.epub"

生成されたドキュメントをブラウザで見てみると、普段のhexdocsとは異なるstyleが当たったドキュメントが確認できます。

用途

プロジェクトのコーディング規約や良くある実装パターンをまとめたり、ライブラリならば使用例を多数記述したりと、色々活用ができそうです。

一方で、実際にコードを動かしたいといったモチベーションがあれば、LiveBookの活用を考えるのが良いかなと思いました。ライブラリのドキュメントとしては有用そうです。

まとめ

ex_docのチートシート機能について紹介しました。ex_docを使っているプロジェクトであれば何のハードルもなく導入できるため、ぜひ活用してみてください。

試してみる

用途

まとめ

Discussion