documenting-python-libraries

Python ライブラリのドキュメント

Docstring のスタイル（Google）

def encode(latitude: float, longitude: float, *, precision: int = 12) -> str:
    """Encode geographic coordinates to a quadtree string.

    Args:
        latitude: The latitude in degrees (-90 to 90).
        longitude: The longitude in degrees (-180 to 180).
        precision: Number of characters in output. Defaults to 12.

    Returns:
        A string representing the encoded location.

    Raises:
        ValidationError: If coordinates are out of valid range.

    Example:
        >>> encode(37.7749, -122.4194)
        '9q8yy9h7wr3z'
    """

Sphinx のクイックセットアップ

# Install
uv add --dev sphinx furo myst-parser sphinx-copybutton

# Initialize
sphinx-quickstart docs/

conf.py の必須項目：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',  # Google docstrings
    'myst_parser',          # Markdown support
]
html_theme = 'furo'

pyproject.toml の依存関係

[project.optional-dependencies]
docs = [
    "sphinx>=7.0",
    "furo>=2024.0",
    "myst-parser>=2.0",
]

README のテンプレート

# Package Name

[![PyPI](https://badge.fury.io/py/package.svg)](https://pypi.org/project/package/)

Short description of what it does.

## Installation

uv add package

## Quick Start

from package import function
result = function(args)

## Documentation

Full docs at [package.readthedocs.io](https://package.readthedocs.io/)

ReadTheDocs（.readthedocs.yaml）

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
sphinx:
  configuration: docs/conf.py
python:
  install:
    - method: pip
      path: .
      extra_requirements: [docs]

詳しいセットアップについては、以下をご覧ください。

• SPHINX_CONFIG.md - Sphinx の設定全般
• TUTORIALS.md - チュートリアルの執筆ガイド

チェックリスト

README:
- [ ] Clear project description
- [ ] Installation instructions
- [ ] Quick start example
- [ ] Link to full documentation

API Docs:
- [ ] All public functions documented
- [ ] Args, Returns, Raises sections
- [ ] Examples in docstrings
- [ ] Type hints included

詳細情報

このスキルは、高品質な Python ライブラリの開発ガイド（Will McGinnis 著）の「ドキュメント」セクションに基づいています。詳しくは、以下の記事をご覧ください。

• 効果的な Docstring の書き方
• Sphinx を始める
• ドキュメントのデプロイを自動化する
• ライブラリの API をドキュメント化する