Skip to content

Commit af8d0ce

Browse files
hellowachellowac
committed
add: 新增中文文档翻译
1 parent 27edc06 commit af8d0ce

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+6746
-0
lines changed

‎cn_docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎cn_docs/_static/logo.png

13.4 KB
Loading

‎cn_docs/_static/releasing.drawio

+121
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
<mxfile host="Electron" type="device">
2+
<diagram name="Seite-1" id="xmn08oupI2gSAHxAwkuE">
3+
<mxGraphModel dx="394" dy="220" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
4+
<root>
5+
<mxCell id="0" />
6+
<mxCell id="1" parent="0" />
7+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-33" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;arcSize=21;" parent="1" vertex="1">
8+
<mxGeometry x="130" y="790" width="280" height="290" as="geometry" />
9+
</mxCell>
10+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-21" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;" parent="1" vertex="1">
11+
<mxGeometry x="60" y="330" width="480" height="250" as="geometry" />
12+
</mxCell>
13+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-1" target="Sy3GnD-ZVnJThFurnhwo-3" edge="1">
14+
<mxGeometry relative="1" as="geometry" />
15+
</mxCell>
16+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-1" value="python make_release.py" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
17+
<mxGeometry x="180" y="80" width="120" height="60" as="geometry" />
18+
</mxCell>
19+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-3" target="Sy3GnD-ZVnJThFurnhwo-5" edge="1">
20+
<mxGeometry relative="1" as="geometry" />
21+
</mxCell>
22+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-3" value="Manually adjust CHANGELOG.md changes" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
23+
<mxGeometry x="180" y="170" width="120" height="60" as="geometry" />
24+
</mxCell>
25+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-9" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-5" target="Sy3GnD-ZVnJThFurnhwo-8" edge="1">
26+
<mxGeometry relative="1" as="geometry" />
27+
</mxCell>
28+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-10" value="Yes" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="Sy3GnD-ZVnJThFurnhwo-9" vertex="1" connectable="0">
29+
<mxGeometry x="0.1768" y="-2" relative="1" as="geometry">
30+
<mxPoint as="offset" />
31+
</mxGeometry>
32+
</mxCell>
33+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-12" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-5" target="Sy3GnD-ZVnJThFurnhwo-11" edge="1">
34+
<mxGeometry relative="1" as="geometry" />
35+
</mxCell>
36+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-13" value="No" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="Sy3GnD-ZVnJThFurnhwo-12" vertex="1" connectable="0">
37+
<mxGeometry x="0.3105" y="2" relative="1" as="geometry">
38+
<mxPoint as="offset" />
39+
</mxGeometry>
40+
</mxCell>
41+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-5" value="Is there a breaking change" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
42+
<mxGeometry x="180" y="260" width="120" height="60" as="geometry" />
43+
</mxCell>
44+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-24" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-7" target="Sy3GnD-ZVnJThFurnhwo-23" edge="1">
45+
<mxGeometry relative="1" as="geometry" />
46+
</mxCell>
47+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-7" value="Adjust the CHANGELOG.md" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
48+
<mxGeometry x="170" y="600" width="120" height="60" as="geometry" />
49+
</mxCell>
50+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-17" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-8" target="Sy3GnD-ZVnJThFurnhwo-7" edge="1">
51+
<mxGeometry relative="1" as="geometry">
52+
<Array as="points">
53+
<mxPoint x="150" y="460" />
54+
<mxPoint x="230" y="460" />
55+
</Array>
56+
</mxGeometry>
57+
</mxCell>
58+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-8" value="Major version bump in _version.py" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
59+
<mxGeometry x="90" y="370" width="120" height="60" as="geometry" />
60+
</mxCell>
61+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-15" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-11" target="Sy3GnD-ZVnJThFurnhwo-14" edge="1">
62+
<mxGeometry relative="1" as="geometry" />
63+
</mxCell>
64+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-16" value="Yes" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="Sy3GnD-ZVnJThFurnhwo-15" vertex="1" connectable="0">
65+
<mxGeometry x="-0.2562" y="3" relative="1" as="geometry">
66+
<mxPoint as="offset" />
67+
</mxGeometry>
68+
</mxCell>
69+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-20" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-11" target="Sy3GnD-ZVnJThFurnhwo-19" edge="1">
70+
<mxGeometry relative="1" as="geometry" />
71+
</mxCell>
72+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-11" value="Is there a new feature?" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
73+
<mxGeometry x="250" y="370" width="120" height="60" as="geometry" />
74+
</mxCell>
75+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-18" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-14" target="Sy3GnD-ZVnJThFurnhwo-7" edge="1">
76+
<mxGeometry relative="1" as="geometry" />
77+
</mxCell>
78+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-14" value="Minor version bump" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
79+
<mxGeometry x="250" y="490" width="120" height="60" as="geometry" />
80+
</mxCell>
81+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-35" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-19" target="Sy3GnD-ZVnJThFurnhwo-23" edge="1">
82+
<mxGeometry relative="1" as="geometry" />
83+
</mxCell>
84+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-19" value="Patch version bump" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
85+
<mxGeometry x="400" y="490" width="120" height="60" as="geometry" />
86+
</mxCell>
87+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-22" value="Semantic Versioning" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontStyle=1;fontSize=18;fontColor=#6E6E6E;" parent="1" vertex="1">
88+
<mxGeometry x="450" y="350" width="60" height="30" as="geometry" />
89+
</mxCell>
90+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-27" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-23" edge="1">
91+
<mxGeometry relative="1" as="geometry">
92+
<mxPoint x="230" y="810" as="targetPoint" />
93+
</mxGeometry>
94+
</mxCell>
95+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-23" value="git commit -eF RELEASE_COMMIT_MSG.md" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
96+
<mxGeometry x="75" y="700" width="310" height="60" as="geometry" />
97+
</mxCell>
98+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-30" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" target="Sy3GnD-ZVnJThFurnhwo-28" edge="1">
99+
<mxGeometry relative="1" as="geometry">
100+
<mxPoint x="230" y="870" as="sourcePoint" />
101+
</mxGeometry>
102+
</mxCell>
103+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-31" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="Sy3GnD-ZVnJThFurnhwo-28" target="Sy3GnD-ZVnJThFurnhwo-29" edge="1">
104+
<mxGeometry relative="1" as="geometry" />
105+
</mxCell>
106+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-28" value="Build and push packages to PyPI" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
107+
<mxGeometry x="170" y="910" width="120" height="60" as="geometry" />
108+
</mxCell>
109+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-29" value="Create release on GitHub" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
110+
<mxGeometry x="170" y="1010" width="120" height="60" as="geometry" />
111+
</mxCell>
112+
<mxCell id="Sy3GnD-ZVnJThFurnhwo-36" value="GitHub Action" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontStyle=1;fontSize=18;fontColor=#6F9958;" parent="1" vertex="1">
113+
<mxGeometry x="325" y="813" width="60" height="30" as="geometry" />
114+
</mxCell>
115+
<mxCell id="srRZveQdFgRCeiaoivwE-1" value="Create tag on&lt;div&gt;GitHub&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
116+
<mxGeometry x="170" y="810" width="120" height="60" as="geometry" />
117+
</mxCell>
118+
</root>
119+
</mxGraphModel>
120+
</diagram>
121+
</mxfile>

‎cn_docs/_static/releasing.drawio.png

290 KB
Loading

‎cn_docs/conf.py

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
"""
2+
Configuration file for the Sphinx documentation builder.
3+
4+
This file only contains a selection of the most common options.
5+
For a full list see the documentation:
6+
https://www.sphinx-doc.org/en/master/usage/configuration.html
7+
"""
8+
# -- Path setup --------------------------------------------------------------
9+
10+
# If extensions (or modules to document with autodoc) are in another directory,
11+
# add these directories to sys.path here. If the directory is relative to the
12+
# documentation root, use os.path.abspath to make it absolute, like shown here.
13+
import datetime
14+
import os
15+
import shutil
16+
import sys
17+
18+
sys.path.insert(0, os.path.abspath("."))
19+
sys.path.insert(0, os.path.abspath("../"))
20+
21+
import pypdf as py_pkg
22+
23+
# shutil.copyfile("../CHANGELOG.md", "meta/CHANGELOG.md")
24+
# shutil.copyfile("../CONTRIBUTORS.md", "meta/CONTRIBUTORS.md")
25+
26+
# -- Project information -----------------------------------------------------
27+
28+
project = py_pkg.__name__
29+
copyright = f"2006 - {datetime.datetime.now(tz=datetime.timezone.utc).year}, Mathieu Fenniak and pypdf contributors"
30+
author = "Mathieu Fenniak"
31+
32+
# The version info for the project you're documenting, acts as replacement for
33+
# |version| and |release|, also used in various other places throughout the
34+
# built documents.
35+
#
36+
# The short X.Y version.
37+
version = py_pkg.__version__
38+
# The full version, including alpha/beta/rc tags.
39+
release = py_pkg.__version__
40+
41+
# -- General configuration ---------------------------------------------------
42+
# If your documentation needs a minimal Sphinx version, state it here.
43+
needs_sphinx = "4.0.0"
44+
45+
# Add any Sphinx extension module names here, as strings. They can be
46+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
47+
# ones.
48+
extensions = [
49+
"sphinx.ext.autodoc",
50+
"sphinx.ext.intersphinx",
51+
"sphinx.ext.autosummary",
52+
"sphinx.ext.coverage",
53+
"sphinx.ext.mathjax",
54+
"sphinx.ext.viewcode",
55+
"sphinx.ext.napoleon",
56+
# External
57+
"myst_parser",
58+
]
59+
60+
python_version = ".".join(map(str, sys.version_info[:2]))
61+
intersphinx_mapping = {
62+
"python": (f"https://docs.python.org/{python_version}", None),
63+
"Pillow": ("https://pillow.readthedocs.io/en/latest/", None),
64+
}
65+
66+
nitpick_ignore_regex = [
67+
# For reasons unclear at this stage the io module prefixes everything with _io
68+
# and this confuses sphinx
69+
(
70+
r"py:class",
71+
r"(_io.(FileIO|BytesIO|Buffered(Reader|Writer))|pypdf.*PdfDocCommon)",
72+
),
73+
]
74+
75+
autodoc_default_options = {
76+
"member-order": "bysource",
77+
"members": True,
78+
"show-inheritance": True,
79+
"undoc-members": True,
80+
}
81+
autodoc_inherit_docstrings = False
82+
autodoc_typehints_format = "short"
83+
python_use_unqualified_type_names = True
84+
85+
# Add any paths that contain templates here, relative to this directory.
86+
templates_path = ["_templates"]
87+
88+
# List of patterns, relative to source directory, that match files and
89+
# directories to ignore when looking for source files.
90+
# This pattern also affects html_static_path and html_extra_path.
91+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
92+
93+
# Configure MyST extension.
94+
myst_all_links_external = False
95+
myst_heading_anchors = 3
96+
97+
98+
# -- Options for HTML output -------------------------------------------------
99+
100+
language = "zh_CN"
101+
102+
# The theme to use for HTML and HTML Help pages. See the documentation for
103+
# a list of builtin themes.
104+
#
105+
# html_theme = "sphinx_rtd_theme"
106+
html_theme = "furo"
107+
108+
# Theme options are theme-specific and customize the look and feel of a theme
109+
# further. For a list of options available for each theme, see the
110+
# documentation.
111+
# html_theme_options = {
112+
# "canonical_url": "",
113+
# "analytics_id": "",
114+
# "logo_only": True,
115+
# "prev_next_buttons_location": "bottom",
116+
# "style_external_links": False,
117+
# # Toc options
118+
# "collapse_navigation": True,
119+
# "sticky_navigation": True,
120+
# "navigation_depth": 4,
121+
# "includehidden": True,
122+
# "titles_only": False,
123+
# }
124+
html_theme_options = {} # type: ignore
125+
html_logo = "_static/logo.png"
126+
127+
128+
# Add any paths that contain custom static files (such as style sheets) here,
129+
# relative to this directory. They are copied after the builtin static files,
130+
# so a file named "default.css" will overwrite the builtin "default.css".
131+
html_static_path = ["_static"]
132+
133+
# -- Options for Napoleon -----------------------------------------------------
134+
135+
napoleon_google_docstring = True
136+
napoleon_numpy_docstring = False # Explicitly prefer Google style docstring
137+
napoleon_use_param = True # for type hint support
138+
napoleon_use_rtype = False # False so the return type is inline with the description.

‎cn_docs/dev/PR_Header_example.png

20.3 KB
Loading

‎cn_docs/dev/cmaps.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# CMaps
2+
3+
查看 "crazyones" 的 cmap：
4+
5+
```bash
6+
pdftk crazyones.pdf output crazyones-uncomp.pdf uncompress
7+
```
8+
9+
你会看到以下内容：
10+
11+
```text
12+
begincmap
13+
/CMapName /T1Encoding-UTF16 def
14+
/CMapType 2 def
15+
/CIDSystemInfo <<
16+
/Registry (Adobe)
17+
/Ordering (UCS)
18+
/Supplement 0
19+
>> def
20+
1 begincodespacerange
21+
<00> <FF>
22+
endcodespacerange
23+
1 beginbfchar
24+
<1B> <FB00>
25+
endbfchar
26+
endcmap
27+
CMapName currentdict /CMap defineresource pop
28+
```
29+
30+
---
31+
32+
## codespacerange
33+
34+
`codespacerange` 将完整的字节序列映射到一系列 Unicode 字形。
35+
它定义了一个起始点：
36+
37+
```text
38+
1 beginbfchar
39+
<1B> <FB00>
40+
```
41+
42+
这意味着 `1B`（十六进制 27）映射到 Unicode 字符 [`FB00`](https://unicode-table.com/en/FB00/) - 即连字符 **ff**（两个小写字母 f）。
43+
44+
`begincodespacerange` 中的两个数字表示范围的起始偏移量为 0（因此从 `1B ➜ FB00`），直到偏移量 `FF`（十进制 255）。因此，`1B + FF = 282` 映射到 Unicode 字符 [`FBFF`](https://www.compart.com/de/unicode/U+FBFF)。
45+
46+
在文本流中，存在以下内容：
47+
48+
```text
49+
(The)-342(mis\034ts.)
50+
```
51+
52+
其中 `\034` 是八进制，表示十进制的 28。

‎cn_docs/dev/deprecations.md

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# 弃用流程
2+
3+
pypdf 致力于为现有用户和新用户提供卓越的库。我们在引入可能导致不兼容更改时非常谨慎，但如果这些更改从长远来看对社区有益，我们会推进实施。
4+
5+
我们希望并认为弃用不会经常发生。如果确实发生，用户可以依赖以下流程。
6+
7+
---
8+
9+
## 语义化版本控制
10+
11+
pypdf 遵循[语义化版本控制](https://semver.org/)。如果您想避免破坏性更改，请使用依赖版本固定（也称为版本锁定）。在 Python 中，可以通过在 `requirements.txt` 文件中指定所需的确切版本来实现。一个可以支持此操作的工具是 [`pip-tools`](https://pypi.org/project/pip-tools/) 提供的 `pip-compile`。
12+
13+
如果您使用 [Poetry](https://pypi.org/project/poetry/)，则可以通过 `poetry.lock` 文件来实现版本锁定。
14+
15+
---
16+
17+
## pypdf 如何弃用功能
18+
19+
假设当前的 pypdf 版本为 `x.y.z`。经过讨论（例如通过 GitHub issue），我们决定移除某个类/函数/方法。以下是具体流程：
20+
21+
1. **`x.y.(z+1)`**：
22+
添加一个 **DeprecationWarning**（弃用警告）。如果存在替代方案，同时引入替代方案，并在警告中说明变更内容及实施时间。
23+
- 文档中会告知用户该功能已弃用、实施时间及新功能。
24+
- CHANGELOG 中会记录此信息。
25+
26+
2. **`(x+1).0.0`**：
27+
删除/修改代码，进行破坏性更改，将 **DeprecationWarning** 替换为 **DeprecationError**（弃用错误）。
28+
- 这样做是为了帮助之前没有注意警告的用户。
29+
- CHANGELOG 中会记录此信息。
30+
31+
3. **`(x+2).0.0`**：
32+
移除 **DeprecationError**。
33+
34+
---
35+
36+
这意味着用户将收到三次提醒：
37+
1. 在 CHANGELOG 中的 3 次警告；
38+
2. 在下一个主要版本发布前的 **DeprecationWarning**；
39+
3. 在下一个主要版本后的 **DeprecationError**。
40+
41+
---
42+
43+
**注意**：添加警告可能对某些用户（尤其是在 CI 环境中）造成破坏性影响。因此，必须提供充分的文档说明。

0 commit comments

Comments
 (0)