Elixirと闘魂で文書革命！公式風の二列レイアウト文書を作成しよう

defmodule FightingSpirit do
  def shout do
    IO.puts "元氣ですかーーーッ！！！"
    IO.puts "元氣があればなんでもできる！"
    IO.puts "闘魂とは己に打ち克つこと。"
    IO.puts "そして闘いを通じて己の魂を磨いていく"
    IO.puts "ことだと思います。"
  end
end

FightingSpirit.shout()

$\huge{元氣ですかーーーーッ！！！}$
$\huge{元氣があればなんでもできる！}$

$\huge{闘魂とは己に打ち克つこと。}$
$\huge{そして闘いを通じて己の魂を磨いていく}$
$\huge{ことだと思います。}$

はじめに

Elixirでのドキュメント作成に利用されるex_docでは、HTML形式で豊富な表現ができます。
本記事では、公式ドキュメントのEnum cheatsheetのような2列のレイアウトのドキュメントの作成方法を解説します。

早速実践

早速実践してみます。行動あるのみです。

プロジェクトの作成

まずはElixirプロジェクトを作ります。
今回は、helloという名前でElixirのプロジェクトを作ります。

mix new hello
cd hello

次にmix.exsを2箇所編集します。

ex_docの追加

ex_docを追加します。

mix.exs

  defp deps do
    [
      {:ex_doc, "~> 0.34", only: :dev, runtime: false}
    ]
  end

.cheatmdの追加

:docsで指定するリストの中の:extrasに格納する.cheatmdファイルの名前を書きます。

mix.exs

  def project do
    [
      app: :hello,
      version: "0.1.0",
      elixir: "~> 1.17",
      start_permanent: Mix.env() == :prod,
      deps: deps(),
      docs: [
        extras: ["cheatsheet.cheatmd"]
      ]
    ]
  end

.cheatmdファイルの作成

文法はCheatsheet Exampleで学んでください。
ここでは以下のものを拝借します。

2列レイアウトは、{: .col-2}で指定しています。

あとはドキュメントの作成のみです。

ドキュメントの作成

まずは依存関係を解決します。

mix deps.get

そしてドキュメントの作成です。

mix docs

index.htmlを開く

doc/index.htmlができています。macOSでは以下のコマンドで開けます。

open doc/index.html

これで公式ドキュメントのEnum cheatsheetのような2列のレイアウトのドキュメントができます。
写真は試しに{: .col-3}と指定したときの出来上がりの様子です。
3列です！！！

---

公式ドキュメント

ex_docの公式ドキュメントでは、Additional pagesの節に説明が書いてあります。
この記事で紹介した.cheatmdに加えて、.mdと.livemdの話も書いてありますので気になる方はご覧になってください。

---

さいごに

ex_docは、Elixirの公式ドキュメントでも使っているドキュメント作成ツールです。ex_docのさまざまな機能を使って読者にとってわかりやすいドキュメントを提供しましょう！

道を切り開け！書く一文字が記事となり、その記事が力となる。己の闘魂を燃やし、世界へ発信し続けよ。Elixirと共にさらなる高みへ、今こそ踏み出せ！