rewrite-python-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rewrite Python Docs

重写Python文档

Use source code as the source of truth. Treat existing docs, docstrings, tests, and examples only as weak hints.

以源代码为唯一可信来源。将现有文档、文档字符串、测试及示例仅视为参考提示。

Guidelines

指南

Run
```
scripts/gen-ref-pages.py
```
to regenerate reference pages under
```
docs/reference/
```
. The script will output a navigation table that can be copy-pasted into
```
zensical.toml
```
.
Files to update:
- docstrings in source code
- ```
docs/
```
  (excluding generated
```
docs/reference/
```
  )
- description in
```
pyproject.toml
```
  and
```
zensical.toml
```
- inventories in
```
zensical.toml
```
  if needed
DO NOT EDIT:
- generated reference pages under
```
docs/reference/
```
Existing docs, docstrings, tests, examples may be rough, missing, incomplete or misleading, it only serves as weak hint.
Favor bold, comprehensive rewrites over minor or incremental edits.
Keep docs concise, fluent, example-first.
Source code is the source of truth.
Use Google style docstrings. Read google-style.md for details.
Use markdown in docstrings:
- Use single backticks for inline code, NOT double backticks.
- Cross-references are written as Markdown reference-style links: [
```
Object 1
```
  ][full.path.object1].

运行
```
scripts/gen-ref-pages.py
```
以重新生成
```
docs/reference/
```
下的参考页面。该脚本会输出一个导航表，可直接复制粘贴到
```
zensical.toml
```
中。
需要更新的文件：
- 源代码中的文档字符串
- ```
docs/
```
  目录（不包括自动生成的
```
docs/reference/
```
  ）
- ```
pyproject.toml
```
  和
```
zensical.toml
```
  中的描述信息
- 必要时更新
```
zensical.toml
```
  中的清单
禁止编辑：
- ```
docs/reference/
```
  下自动生成的参考页面
现有文档、文档字符串、测试及示例可能粗糙、缺失、不完整或有误导性，仅作为参考提示。
优先选择全面、彻底的重写，而非小幅或增量修改。
保持文档简洁流畅，以示例为先。
源代码为唯一可信来源。
使用Google风格的文档字符串。详情请阅读google-style.md。
在文档字符串中使用Markdown：
- 行内代码使用单个反引号，而非双反引号。
- 交叉引用采用Markdown参考式链接格式：[
```
Object 1
```
  ][full.path.object1]。

Suggested Layout

建议目录结构

text

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

Keep only the sections the project needs.
Keep navigation shallow.

text

docs/
  README.md
  getting-started/
    ...
  guides/
    ...
  concepts/
    ...
  reference/  # 自动生成，禁止编辑
    package/
      README.md
      submodule.md
  advanced/
    ...

仅保留项目所需的目录。
保持导航层级简洁。

mkdocstrings Notes

mkdocstrings注意事项

The project uses
```
zensical
```
with
```
mkdocstrings
```
.
The
```
__init__
```
method is merged into the class' signature and docstring.
The first line in
```
__init__
```
methods' docstrings is ignored.

项目使用
```
zensical
```
搭配
```
mkdocstrings
```
。
```
__init__
```
方法会合并到类的签名和文档字符串中。
```
__init__
```
方法文档字符串的第一行将被忽略。

Validation

验证步骤

Run
```
rumdl fmt .
```
. Treat its findings as weak hints, not strong constraints.
Run
```
mise run lint
```
.
Run
```
mise run docs:build
```
.
If validation fails for unrelated reasons, separate those failures from the docs change and report them clearly.

运行
```
rumdl fmt .
```
。将其检查结果视为参考提示，而非强制约束。
运行
```
mise run lint
```
。
运行
```
mise run docs:build
```
。
如果验证因无关原因失败，请将这些失败与文档修改分开，并清晰报告。