rewrite-python-docs

Python ドキュメントを書き直す

ソースコードを信頼できる情報源としてください。既存のドキュメント、docstring、テスト、サンプルは、あくまで参考程度に扱ってください。

ガイドライン

• 編集前に、pyproject.toml、zensical.toml、noxfile.py、.config/mise/、公開エクスポート、ソースコード、テストを確認してください。
• scripts/gen-ref-pages.py を実行して、docs/reference/ 以下のリファレンスページを再生成してください。このスクリプトは、zensical.toml にコピー＆ペーストできるナビゲーションテーブルを出力します。
• 更新するファイル：
  • ソースコード内のdocstring
  • docs/（生成済みの docs/reference/ を除く）
  • pyproject.toml と zensical.toml の説明
  • 必要に応じて zensical.toml のインベントリ
• 編集禁止：
  • docs/reference/ 以下の生成済みリファレンスページ
• 既存のドキュメント、docstring、テスト、サンプルは、粗雑、不足、不完全、または誤解を招く可能性があり、参考程度にしかなりません。
• 小さな修正や段階的な編集よりも、大胆で包括的な書き直しを優先してください。
• ドキュメントは簡潔で、読みやすく、サンプルを先に示す構成にしてください。
• ソースコードを信頼できる情報源としてください。
• Google スタイルのdocstringを使用してください。詳細はgoogle-style.mdを参照してください。
• サンプルが決定的で、有用で、実行可能な公開 API には、コンパクトなdoctestを含む Examples: セクションを優先してください。
• doctestは飾りではなく、実行可能なテストとして扱ってください。フィクスチャが多いもの、パラメーター化されたもの、または不安定な動作は tests/ に置いてください。
• docstringではMarkdownを使用してください。
  • インラインコードにはシングルバッククォートを使用し、ダブルバッククォートは使用しないでください。
  • 相互参照は、Markdownの参照形式リンクで記述してください：[Object 1][full.path.object1]。

推奨レイアウト

docs/
  README.md
  getting-started/
    ...
  guides/
    ...
  concepts/
    ...
  reference/  # generated, DO NOT EDIT
    package/
      README.md
      submodule.md
  advanced/
    ...

• プロジェクトに必要なセクションだけを残してください。
• ナビゲーションは浅い階層にしてください。

mkdocstrings に関する注意

• このプロジェクトでは、mkdocstrings と zensical を使用しています。
• __init__ メソッドは、クラスのシグネチャとdocstringに統合されます。
• __init__ メソッドのdocstringの1行目は無視されます。

検証

• rumdl fmt . を実行してください。検出事項は強い制約ではなく、参考程度に扱ってください。
• 変更したdoctestに対して uv run pytest ... を実行してください。
• mise run lint を実行してください。
• mise run docs:build を実行してください。
• 検証が無関係な理由で失敗した場合は、その失敗とドキュメント変更を切り分け、明確に報告してください。