ドキュメントの書き方¶
このページは、公開ドキュメントの構成の決め方と書き方の規則です。ページを足したり直したりするときは、まずここで置き場所を決めてください。
読者と構成¶
ドキュメントは3種類の読者を想定しています。
| 読者 | 求めるもの | 主に読む所 |
|---|---|---|
| 解析する人（主な読者） | データを読んで図を描く方法、データの意味と注意点 | はじめる、ガイド、データ |
| 試作を使う研究者 | 研究用モデルの定義、全期間の計算の回し方 | 試作API |
| 開発に加わる人 | 設計の基準、拡張の手順、検証とリリース | 開発 |
セクションごとに、書く内容を次のように分けます。
| セクション | 書く内容 | 書かない内容 |
|---|---|---|
| はじめる | 初めての人が順に読む4ページ。1つの流れに沿って最小限の手順を示す | 全オプションの網羅（ガイドへリンクする） |
| ガイド | 機能ごとの使い方と仕組み。1つの話題を1ページで完結させる | 特定の機器だけの事情（データへ） |
| データ | データ源ごとの変数・単位・座標系・取得元・校正・品質・制約 | 機器に依存しない機能の説明（ガイドへ） |
| 試作API | 試作の使い方・モデルの定義・限界 | 特定の期間の計算結果、比較の図、考察（working/へ） |
| リファレンス | 引くための表。API、スキーマ、ファイル形式、CLI、用語 | 手順や経緯 |
| 開発 | 設計の基準、拡張・検証・リリースの手順 | 利用者向けの使い方 |
1つの話題は1ページに書く¶
同じ説明を複数のページに書くと、片方だけが更新されて食い違います。ある話題を正式に説明するページを1つに決め、 他のページからはリンクします。たとえばStoreの層はStoreにデータを保存する、 設定の優先順位は設定だけに書きます。 「はじめる」は流れを示すために一部を繰り返しますが、詳細はガイドに任せます。
実装の状況も同じ考え方で、機能のすぐ近くに書きます。データ源ごとの対応はデータ一覧の表、 未実装の点は各ページの「制約」の節、予定と構想は設計方針に置き、別の「実装状況」のページは作りません。
ページのひな形¶
データのページは、次の順にそろえます。読者が機器をまたいで同じ場所を探せるようにするためです。
- 何を測った、どのデータか（1〜2文）と、最短のコード例
- 変数（入口、次元、単位、座標系、内容の表）
- 読み込み・作図の例
- 元ファイルの取得と置き場所
- 校正・欠測・品質の扱い
- 制約（未実装、未検証の点）
- 出典
ガイドのページは、冒頭の1〜2文でそのページが答える問いを示し、仕組みの説明と手順を交互に置きます。 引数の一覧は表にします。
文体¶
- 日本語版は「です・ます」で書き、結論から述べます。見出しは、読めば内容が分かる短い文か名詞句にします。
- 用語は用語集の訳に合わせます。API名・外部の仕様名・ファイル名は原名のまま
codeで書き、 日本語との間に空白は入れません。 - 数式は
$...$と$$...$$、単位はnT、eV/(cm^2 s sr eV)のようにスキーマと同じ表記にします。 - 一般的な留保は繰り返さず、判断に効く制約や未検証の点を、該当する説明のそばに具体的に書きます。
- コード例は、実装と照らして動くものだけを載せます。説明のための変数（
timeなど）は、ページの中で一度定義します。 - 図はMarkdownで埋め込み、実データから作ったものを
docs/assets/に置きます。
日本語と英語¶
日本語版（docs/ja/）を正本とし、英語版（docs/en/）を同じパスに置きます。
ビルドはmkdocs-static-i18nで行い、日本語版をサイトのルート、英語版を/en/に出力します。
ナビゲーションの見出しはmkdocs.ymlのnavに日本語で書き、英語の見出しはnav_translationsに書きます。
英語版のページが無いと日本語版を代わりに表示しますが、tests/test_docs_build.pyがすべてのページの英語版があることを確かめます。
ページの右上の切り替え（Lang: 日本語/English）はdocs/overrides/partials/alternate.htmlで、同じパスの対応ページへ移ります。
自動で生成するページ¶
| ページ | 生成元 | 更新 |
|---|---|---|
| スキーマ | コードのInstrumentSchema |
python -m sopran.schema_docs docs/ja/reference/schemas.md（英語版は--language en） |
| Python API | docstring（mkdocstrings） | ビルド時に自動。載せるクラスと関数はページに列挙する |
コードから参照しているURL¶
guide()が返す説明には、公開ドキュメントのURLが入っています。URLはページのパスから
sopran.core.pages.public_doc_urls("data/kaguya/")で日本語版と英語版の両方を作ります。
ページを移したときは、次の定数とtests/test_docs_build.pyなどのテストも直します。
| 定数 | 場所 |
|---|---|
_PUBLIC_DOC_PATHS |
src/sopran/missions/kaguya/mission.py |
_PUBLIC_DOC_URLS |
src/sopran/missions/artemis/mission.py |
PUBLIC_DOC_URLS |
src/sopran/bodies/moon/guides.py |
ページを足すときの手順¶
- 上の表で置き場所を決め、同じ話題のページが無いか確かめる。
docs/ja/とdocs/en/の同じパスにページを作る。mkdocs.ymlのnavに日本語の見出しを、nav_translationsに英語の見出しを加える。- 関連するページからリンクする。
python -m mkdocs build --strictで、リンク切れ・アンカー切れが無いことを確かめる。mkdocs serveで表示を確かめられます（pip install -e ".[docs]"が必要です）。