Guidedog / ドキュメント
0.2.0
コードベースの文書化¶
公開する名前には契約が必要だ。入力、結果、所有権、失敗する条件を説明する。シグネチャだけではマニュアルにならない。
Odin¶
odin_autoapi_dirs = ["../../lib"]
odin_autoapi_root = "api"
odin_autoapi_options = ["members", "undoc-members"]
Guidedog は Odin のパーサーでソースを読む。対象パッケージをコンパイルしたり実行したりしない。生成ページは文書グラフとオブジェクト一覧に加わる。このリポジトリの独立した API プロジェクトは docs/api。ディレクティブ、シグネチャ、オプションは Odin の文書化 を参照。
Python¶
extensions = ["sphinx.ext.autodoc"]
autodoc_source_paths = ["../src"]
Guidedog は Python ソースを解析し、インポートしない。これでインポートの副作用を避けるが、実行時に生成されるオブジェクトは見つからないことがある。公開インターフェースの一部なら明示的に説明する。探索規則の詳細は autodoc による Python のドキュメント作成 を参照。
プロジェクト間のリンク¶
生成した objects.inv をサイトと一緒に公開する。他のプロジェクトから intersphinx のマッピングで名前を解決できる。再現可能なビルドには明示的なマッピングを使う。他のプロジェクトへのリンク を参照。