Elixir プロジェクトの moduledoc を README.md からコピーする

Elixir プロジェクトを Hex パッケージとしてリリースする際には、ドキュメントを書かきますが、パッケージのうたい文句を書く部分が複数あり同じ内容を何箇所かに複写することもあると思います。

最近、便利な技を覚えたのご紹介いたします。

やりかた

1. README.md でうたい文句を<!-- MODULEDOC -->で挟む

README.md

<!-- MODULEDOC -->
Read temperature and pressure in Elixir from Bosch environmental sensors
<!-- MODULEDOC -->

2. @moduledoc の文字列を動的に README.md から複写

my_project.ex

defmodule MyProject do
  @moduledoc File.read!("README.md")
             |> String.split("<!-- MODULEDOC -->")
             |> Enum.fetch!(1)

このように書くと、以下のようなコードがコンパイル時に生成されます。

my_project.ex

defmodule MyProject do
  @moduledoc """
  Read temperature and pressure in Elixir from Bosch environmental sensors
  """

ドキュメントの書き方

Elixir では言語自体にドキュメントを書きやすく、ドキュメントを効果的に使えるようにする仕組みが組み込まれているので、気持ちよく書けます。ドキュメントに書かれたサンプルコードをテストとして実行することもできます。

ネタ元

誰が最初にはじめたのか知りませんが、確か自分はこれを参考にした気がします。

コミュニティ

いろんなコミュニティから刺激と元氣をいただいています。ありがとうございます。

闘魂コミュニティ

みんなでわいわい楽しく自由に闘魂プログラミングをしています。

ぜひお気軽にお立ち寄りください。

Nervesで組み込み開発するコミュニティ

「Elixir で IoT！？ナウでヤングで cool な Nerves フレームワーク」です。

Elixir 言語でワクワクするコミュニティ