Help us understand the problem. What is going on with this article?

Elm開発でもドキュメントが書きたい!

副タイトル:applicationモードだとdocs.jsonは生成できないんですよってもう言わなくていいんだ

Elmのパッケージサイトでは各パッケージのドキュメントが読めます
このドキュメントはREADMEと各moduleに書かれたmodule documentから生成されています

おそらくパッケージを出したことがないとあまり馴染みがないと思われるのでmodule documentの書き方とelm-doc-previewを利用したオフラインパッケージサイトの作り方を書いておこうと思います

オフラインパッケージサイトを作ることで新しくプロジェクトに入ったひとや未来の自分のために分かりやすいドキュメンテーションができます(わかりやすいかどうかは努力による)

module documentの書き方

公式のフォーマットの説明を読みましょう
英語が読めない?しょうがないなあ

  • {-| -}こういうのを関数の上とかmodule宣言(ファイルの一番上に書くmodule Hoge exposing(..))とimport文の間に書く
  • 基本的にmarkdownが書ける
    • 見出し(#*)は3つまでしかあんまり意味がない。見た目が変わらないため
    • Elmのコードブロックはindentして書く
      • バッククォートでも大丈夫。elm-formatが直してくるんで
    • @docs hogeFunc, fugaFuncみたいに書いてそれぞれのドキュメントをその位置に展開する

何を書けばいいのか

自分(もしくは自分たち)のために書くので必要なことを書けばよいでしょう
ちょっと目的が違うかもですがパッケージ向けのガイドラインが参考になると思います

オフラインパッケージサイトを構築する

elm-doc-previewというツールを使ってオフラインパッケージサイトを作ります

Elm-doc-preview 3: Applications support & offline packages documentation serverの記事で紹介されている通り、8/15にバージョンが上がってアプリケーションモードのサポートとキャッシュされたパッケージのドキュメントを読める機能が追加されました
神です

elmにはpackageモードとapplicationモードがあってpackageモードでないとドキュメント用のjsonが出力できないという問題がありました
elm-doc-preview 3ではapplicationモードでもドキュメントをだしてくれるようになったので大変便利です

使ってみる

npm install -g elm-doc-preview

nextから新しいバージョンがとれます(正式リリースされました。感謝
これでelm-doc-previewコマンドとedpコマンド(ただのaliasです)が使えるようになります

あとはコマンド叩くだけでサーバーが立ち上がりますがapplicationサポートをするには1つjsonが必要です

elm-application.json
{
    "name": "dmy/elm-doc-preview",
    "summary": "Documentation previewer",
    "version": "3.0.0",
    "exposed-modules": [
        "Href",
        "Session",
        "Page.Docs.Block",
        "Page.Search",
        "Page.Diff",
        "Page.Problem",
        "Page.Docs",
        "Page.Search.Entry",
        "Release",
        "Utils.Spinner",
        "Utils.OneOrMore",
        "Utils.Logo",
        "Utils.Error",
        "Utils.Markdown",
        "Main",
        "Skeleton"
    ]
}

これをelm.jsonと同じ場所に置いておきましょう。内容は見てわかると思います
exposed-modulesにはドキュメントをみたいモジュールを追加しましょう

これを書いたらその場でコマンドをたたけばサーバーが立ち上がってオフラインパッケージサイトをみることができます

アプリケーションのドキュメントにはおそらく初めてのひとはエラーメッセージが何個か出ていると思います
あれ書けそれ書けと言われるので言われた通りにしましょう
エラーメッセージが親切といわれるElmですが実はpackageをpublishするときにもドキュメントに関して親切にいろいろ言ってくれます

終わりに

コードに書いたコメントがそのままサイトになるやつでした
それなりの規模になった場合何かしら書くことあるので、それを直接ソースコードに書き込んでサイトにすれば共有が簡単になるかと思います

ローカルキャッシュのドキュメントを一覧する機能ですが一度作ってたことがあります。普通に動くようにはなっていますがもう開発することはないと思うのでここに供養します
miyamoen/elm-local-packages

参考: Elmアプリ開発するときに便利な共通モジュールの管理方法

miyamo_madoka
わたしの発言は一くろすすてっちゃ的発言であってー、ぷろぐらみんぐとかえすあいあーとかー所属企業とかー関係なくてーとりあえず何か作りたいなあっていつも思ってますー
elm-jp
主に日本で活動する Elm 利用者のコミュニティです。
https://elm-lang.jp
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした