从零开始系统学习 Python 编程

Appearance

03-文档编写 ​

本章讲解 Python 项目文档的最佳实践。

文档字符串 ​

函数文档字符串 ​

python
def calculate_compound_interest(
    principal: float,
    rate: float,
    time: int,
    compound_frequency: int = 12
) -> float:
    """计算复利。

    Args:
        principal: 本金金额
        rate: 年利率（小数形式，如 0.05 表示 5%）
        time: 投资时间（年）
        compound_frequency: 每年复利次数，默认 12

    Returns:
        最终收益金额（包含本金）

    Raises:
        ValueError: 当本金或利率为负数时

    Example:
        >>> calculate_compound_interest(1000, 0.05, 10)
        1647.009...
    """
    pass

类文档字符串 ​

python
class DatabaseConnection:
    """数据库连接管理器。

    提供与各种数据库的连接管理功能。

    Attributes:
        host (str): 数据库主机地址
        port (int): 数据库端口
        connected (bool): 当前连接状态

    Example:
        >>> db = DatabaseConnection("localhost", 5432, "mydb")
        >>> db.connect()
        >>> db.close()
    """
    pass

Sphinx 文档 ​

安装与配置 ​

bash
# 安装 Sphinx
uv add --dev sphinx sphinx-rtd-theme

# 初始化文档
cd docs
sphinx-quickstart

conf.py 配置 ​

python
# docs/conf.py
project = 'My Package'
release = '1.0.0'

extensions = [
    'sphinx.ext.autodoc',      # 自动生成 API 文档
    'sphinx.ext.napoleon',     # 支持 Google 风格
    'sphinx.ext.viewcode',     # 添加源代码链接
]

html_theme = 'sphinx_rtd_theme'

构建文档 ​

bash
# 构建 HTML 文档
cd docs
make html

# 查看文档
open docs/build/html/index.html

MkDocs 文档 ​

安装与配置 ​

bash
# 安装 MkDocs
uv add --dev mkdocs mkdocs-material

# 初始化
mkdocs new my-docs

mkdocs.yml 配置 ​

yaml
site_name: My Package 文档

theme:
  name: material
  language: zh

nav:
  - 首页: index.md
  - 安装: install.md
  - 使用指南: guide.md
  - API 参考: api.md

预览和构建 ​

bash
# 本地预览
mkdocs serve

# 构建静态站点
mkdocs build

# 部署到 GitHub Pages
mkdocs gh-deploy

README 最佳实践 ​

markdown
# My Package

[![PyPI version](https://badge.fury.io/py/my-package.svg)](https://badge.fury.io/py/my-package)

> 一句话描述你的项目

## 安装

```bash
pip install my-package

快速开始 ​

python
from my_package import Client

client = Client()
result = client.do_something()

功能特点 ​

  • 功能一: 描述
  • 功能二: 描述

文档 ​

完整文档请访问 my-package.readthedocs.io

许可证 ​

MIT License


---

## 本章小结

┌─────────────────────────────────────────────────────────────┐ │ 文档编写 知识要点 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 文档字符串： │ │ ✓ 使用 Google 或 NumPy 风格 │ │ ✓ 包含 Args、Returns、Raises、Example │ │ │ │ 文档工具： │ │ ✓ Sphinx：适合 API 文档 │ │ ✓ MkDocs：适合用户文档 │ │ │ │ README： │ │ ✓ 包含安装、快速开始、功能特点 │ │ │ └─────────────────────────────────────────────────────────────┘