ドキュメント規約

この規約はすべての Luna Flow リポジトリに適用されます。ドキュメントの置き場所、ページの分け方、どのソースを正とするかを定めます。リポジトリは doc/manual/conventions.md に独自の規則を追加できますが、この規約を緩めることはできません。

原則

存在するものを記述する。 ページは現在のブランチにある実装、つまり公開名、振る舞い、その背後にある設計上の判断を記述します。計画は issue に書き、マニュアルには書きません。

英語がソースである。 ページは英語で一度だけ書きます。翻訳はその文章から gettext 翻訳カタログを通じて作られ、ページのコピーとして編集されることはありません。

インターフェースファイルが正である。 MoonBit パッケージでは、pkg.generated.mbti が公開されるインターフェースを定めます。インターフェースファイルにない名前は、公開されたものとして記述しません。

1 ページに 1 つの目的。 ページは API リファレンス、設計ノート、チュートリアル、ガイドのいずれかであり、それらを混在させません。

リポジトリの構成

doc/
├── conf.json                      title, summary and locales
├── manual/                        English source pages
│   ├── index.md                   overview of the repository
│   ├── conventions.md             optional repository-specific rules
│   ├── <guide>.md                 optional guides (getting_started, architecture, ...)
│   ├── api/<package>.md           one chapter per document type,
│   ├── design/<package>.md        one page per package inside it
│   └── tutorial/<package>.md
├── attachments/                   Typst sources, PDFs and images, shared by all locales
└── locale/
    ├── manual.pot                 generated template, never edited
    ├── zh_CN/LC_MESSAGES/manual.po
    └── ja_JP/LC_MESSAGES/manual.po

doc/ にはこれ以外のものを置きません。言語ごとにディレクトリを分ける旧来の構成（doc/en_US、doc/zh_CN など）は lunadoc check で拒否されます。

`conf.json`

{
  "title": "luna-generic",
  "summary": "Algebraic traits and default numeric instances for Luna Flow math packages.",
  "locales": ["zh_CN", "ja_JP"]
}

title はライブラリに表示されるリポジトリ名です。summary はライブラリの一覧に表示される 1 文の概要で、ページ本文と同様に翻訳されます。locales にはリポジトリが維持する翻訳を列挙します。

章とパッケージ

マニュアルはコードの場所ではなく、読者が何を探しているかによって分けられます。ドキュメントの種類ごとに 1 つの章があり、ドキュメント化された MoonBit パッケージはどの章にも 1 ページずつ持ちます。

章	答える問い	パッケージページの内容
`api/`	何を呼び出せるか？	すべての公開型、trait、関数を用途別にまとめ、シグネチャと意味を示します。
`design/`	なぜこうなっているのか？	目標、制約、下した判断、退けた代替案。
`tutorial/`	どう使うのか？	始めから終わりまで通して行う 1 つの作業と、コンパイルできる小さな例。

ページ名はソースルートからのパッケージパスに従います。src/core のパッケージは api/core.md、design/core.md、tutorial/core.md に、src/backend/dense のパッケージは api/backend/dense.md などに記述します。ドキュメント化されたパッケージは、3 つの章すべてにページを持ちます。

リポジトリは conformance/（標準や仕様が何を要求し、パッケージがそれをどう満たすか）、performance/（測定結果とその方法）、integration/（他のパッケージがどう利用するか）の章を追加できます。章には、その章を紹介する index.md を置けます。それ以外の章を設けるには、conventions.md に規則が必要です。

ガイド

manual/ 直下のページは、パッケージをまたぐガイドです（getting_started.md、architecture.md、verification.md など）。ファイル名は小文字とし、単語の間はアンダースコアでつなぎます。

ページの構成

ページはちょうど 1 つのレベル 1 見出しで始めます。これがページのタイトルです。
見出しは文頭だけを大文字にします。「Design Decisions」ではなく「Design decisions」と書きます。
見出しのレベルを飛ばさないでください。
API ページでは、各項目をその名前をコードとして書いた見出しの下に記述します（## `Hom::then` ）。見出しの直後の 1 文で、その項目が何をするかを述べます。
設計ページは、その境界、つまりパッケージが意図的に行わないことで締めくくります。
チュートリアルは最初の段落で目標を述べ、最後に次に読むべきところを示します。

フロントマターは任意です。ある場合は title（ナビゲーションのラベルを見出しと変えたいとき）と description（検索結果用の 1 文）を設定できます。どちらも翻訳されます。

リンク

他のページへは、Markdown ファイルへの相対パスでリンクします（[design](../design/core.md)、[overview](../index.md)）。サイトがそれを各言語の正しいルートに変換します。他のリポジトリへは、https://lunaflow.cn/en/luna-generic/ のようなサイトの絶対 URL でリンクします。ソースコードへは、../../src/hom.mbt のように doc/ の外へ出る相対パスでリンクします。サイトがそれを GitHub へのリンクに変換します。

チェック

lunadoc check は次の場合に失敗します。

conf.json または manual/index.md がない。
廃止された言語別ディレクトリの構成が残っている。
翻訳カタログが英語のソースと一致しない。
相対リンクが存在しないファイルを指している、またはリポジトリの外を指している。
Typst の添付ファイルがコンパイルできない（--compile 指定時）。

fuzzy の翻訳や概要の欠落については警告を出します。