rewrite-python-docs

重写 Python 文档

以源代码为准。现有文档、文档字符串、测试和示例仅作为参考。

指南

• 编辑前检查 pyproject.toml、zensical.toml、noxfile.py、.config/mise/、公开导出项、源代码和测试。
• 运行 scripts/gen-ref-pages.py，重新生成 docs/reference/ 下的参考页面。脚本会输出导航表，可复制粘贴到 zensical.toml 中。
• 需要更新的文件：
  • 源代码中的文档字符串
  • docs/（不包括生成的 docs/reference/）
  • pyproject.toml 和 zensical.toml 中的描述
  • zensical.toml 中的索引（如有需要）
• 不要编辑：
  • docs/reference/ 下生成的参考页面
• 现有文档、文档字符串、测试和示例可能粗略、缺失、不完整或有误导性，只能作为参考。
• 优先进行全面、大幅的重写，而不是细微或渐进式修改。
• 文档应简洁、流畅，并以示例为先。
• 以源代码为准。
• 使用 Google 风格的文档字符串。详情请阅读 google-style.md。
• 对公开 API，若示例具有确定性、实用且可运行，优先使用带精简 doctest 的 Examples: 部分。
• 将 doctest 视为可执行测试，而非装饰性片段；将依赖大量固定数据、参数化或行为不稳定的内容放在 tests/ 中。
• 在文档字符串中使用 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 说明

• 项目使用 zensical 和 mkdocstrings。
• __init__ 方法会合并到类的签名和文档字符串中。
• __init__ 方法文档字符串的首行会被忽略。

验证

• 运行 rumdl fmt .。将其检查结果视为参考，而非严格要求。
• 对已更改的 doctest 运行 uv run pytest ...。
• 运行 mise run lint。
• 运行 mise run docs:build。
• 如果验证因无关原因失败，请将这些问题与文档变更分开，并清楚说明。