Sphinxのドキュメントスタイル

基本的なSphinxのドキュメントのスタイルについて説明する。
必要に応じて冒頭に文章の概要を箇条書きで書く。
必要に応じてメタ情報を付加する。
著者、日付、参考文献、環境、キーワード

ページの階層は最大5階層

階層は最大5階層とする

リスト 4 4階層の例

Portalトップ
|- ガイドライン集(目次)
    |- Gitガイドライン(目次)
        |- Gitの運用ルール(詳細)

リスト 5 5階層の例

Portalトップ
|- AGX Dynamics(目次)
    |- agxTerrain(目次)
        |- agxTerrainの解説(目次)
            |- agxTerrainの土質力学(詳細)

ドキュメントを保存するフォルダ、ファイル名は `snake_case`

フォルダ名、ファイル名はスネークケース snake_case とする
半角英数字のみとする
例: vmt_docs/my_document.rst

ページのセクション(章立て)は最大3階層

ページの章立てはタイトル(章)、節、項の3階層までとする
統一して「セクション」とよぶ

タイトル(レベル1)
=================

節(レベル2)
------------

項(レベル3)
~~~~~~~~~~~~~~

.. rubric:: 小見出し

セクションとは別に見出しを使う場合には ``.. rubric:: 小見出し`` を使う。

参照のターゲット名は `lowerCamelCase`

内部リンクや図、表を参照するためのハイパーリンクターゲット名は lowerCamelCase とする
特定のターゲットには次のように接頭辞をつける

セクション、小見出し	`_sec`	`_secMySection`
図	_fig	`_figMyImage`
表	`_tbl`	`_figMyTable`
その他	`_ref`	`_figSomething`

表記

表記は次を参照する。

箇条書き

階層を浅くするように努める
文が短くなるように努める
- 例外: 議事録やアイデア出し

図表

図表の記述は次を参考にする
- 図、画像(Images)
- 表(Table)
必要に応じて表題(キャプション)をつける
図は横幅を最大720pxとし、次の横幅を目安にする
- 320px 、360px 、480px 、640px 、720px

パラメータの記述

パラメータの説明が短い

フィールドリスト(Field Lists)

パラメータの説明が長い

定義リスト(Definition Lists)

パラメータの量が多い、情報量が多い

表(Table)

パラメータの設定値をまとめて書く

表(Table) を使う
コードブロックをyaml形式で使う

リスト 6 yamlの記述例

name: box
mass: 90
inertia:
    - 100, 0, 0
    - 0, 100, 0
    - 0, 0, 100

参考文献の記述

参考文献は次の記述方法がある。ここでは、sphinxcontrib-bibtexを使う場合について説明する。

Webリンクの記述
sphinxcontrib-bibtexを使った記述

sphinxcontrib-bibtexによる参考文献の記述手順

bibファイルを、次の優先順を参考に配置する
- 参照するページと同じ階層の _assets フォルダ
- 複数のページから参照する場合は、index.rst がある階層の _assets フォルダ
bibファイルにエントリを記述する。記述には @article のみを使う [1] 。
ページに参考文献を表示する。表示方法は次のセクションを参照する。
:cite:`key` で文献へのリンクを表示する

リスト 7 vmtbib_sample.bib

@article{VMTBib2024,
    author={著者 and 団体名},
    title={タイトルtitle},
    journal={雑誌名},
    volume={1},
    number={2},
    pages={3-5},
    year={2024},
    doi={10.1109/5.771073},
    url={https://example.com/},
    urldate={2024-11-14},
}

@article{VMTBib2025,
    author={著者 and 団体名},
    title={タイトルtitle},
    journal={雑誌名},
}

bibファイルの文献を全て表示する

.. bibliography:: _assets/vmtbib_sample.bib
    :style: vmt
    :all:

[VMTBib2024]

著者, 団体名. タイトルtitle. 雑誌名, Vol. 1, No. 2, pp. 3-5, 2024, URL: https://example.com, doi:10.1109/5.771073, (参照 2024-11-14).

[VMTBib2025]

著者, 団体名. タイトルtitle. 雑誌名.

指定の引用キーで引用した文献のみを表示する

:cite:`VMTBib2024`

.. bibliography::
    :style: vmt
    :filter: docname in docnames