【快乐开源】科学计算 API 文档补全

[HydrogenSulfate]

API 文档补全

以下是待补全 docstring 的 API 列表（共 109 个）

序号	API 名称	认领人/状态/PR号
1	ppsci.data.process.transform.CropData	@Liyulingyue #687
2	ppsci.data.process.transform.FunctionalTransform	@Liyulingyue #688
3	ppsci.data.process.transform.Log1p	@Liyulingyue #688
4	ppsci.data.process.transform.Normalize	@Liyulingyue #688
5	ppsci.data.process.transform.Scale	@Liyulingyue #688
6	ppsci.data.process.transform.SqueezeData	@Liyulingyue #688
7	ppsci.data.process.transform.Translate	@Liyulingyue #688
8	ppsci.data.dataset.ERA5SampledDataset	@Liyulingyue #691
9	ppsci.data.dataset.VtuDataset	@Liyulingyue #791
10	ppsci.data.dataset.MeshAirfoilDataset	@MayYouBeProsperous #724
11	ppsci.data.dataset.MeshCylinderDataset	@MayYouBeProsperous #724
12	ppsci.arch.Arch.concat_to_tensor	@megemini #752
13	ppsci.arch.Arch.register_input_transform	@megemini #752
14	ppsci.arch.Arch.register_output_transform	@megemini #752
15	ppsci.arch.Arch.split_to_dict	@megemini #752
16	ppsci.arch.Arch.freeze	@megemini #752
17	ppsci.arch.Arch.unfreeze	@megemini #752
18	ppsci.arch.MLP	@MayYouBeProsperous #732
19	ppsci.arch.DeepONet	@MayYouBeProsperous #732
20	ppsci.arch.DeepPhyLSTM	@megemini #756
21	ppsci.arch.LorenzEmbedding	@Turingg #780
22	ppsci.arch.RosslerEmbedding	@Turingg #780
23	ppsci.arch.CylinderEmbedding	@1want2sleep #840
24	ppsci.arch.Generator	@Turingg #802 #804
25	ppsci.arch.Discriminator	@1want2sleep #840
26	ppsci.arch.PhysformerGPT2	@1want2sleep #840
27	ppsci.arch.ModelList	@1want2sleep #840
28	ppsci.arch.AFNONet	@1want2sleep #840
29	ppsci.arch.PrecipNet	@1want2sleep #840
30	ppsci.arch.UNetEx	@MayYouBeProsperous #724
31	ppsci.arch.NowcastNet	@1want2sleep #840
32	ppsci.autodiff.Jacobians.__call__	@1want2sleep #840
33	ppsci.autodiff.Hessians .__call__	@1want2sleep #840
34	ppsci.autodiff.clear	@1want2sleep #840
35	ppsci.equation.PDE.add_equation	@WoWYoYLoL #846
36	ppsci.equation.PDE.create_function	@WoWYoYLoL #846
37	ppsci.equation.PDE.create_symbols	@WoWYoYLoL #846
38	ppsci.equation.PDE.parameters	@1want2sleep #826
39	ppsci.equation.PDE.set_state_dict	@1want2sleep #826
40	ppsci.equation.PDE.state_dict	@1want2sleep #826
41	ppsci.geometry.Geometry.__and__	@wufei2 #833
42	ppsci.geometry.Geometry.__or__	@wufei2 #833
43	ppsci.geometry.Geometry.__sub__	@wufei2 #833
44	ppsci.geometry.Geometry.__str__	@wufei2 #833
45	ppsci.geometry.Geometry.difference	@wufei2 #833
46	ppsci.geometry.Geometry.intersection	@wufei2 #833
47	ppsci.geometry.Geometry.is_inside	@wufei2 #833
48	ppsci.geometry.Geometry.on_boundary	@wufei2 #833
49	ppsci.geometry.Geometry.periodic_point	@wufei2 #833
50	ppsci.geometry.Geometry.random_boundary_points	@wufei2 #833
51	ppsci.geometry.Geometry.random_points	@wufei2 #833
52	ppsci.geometry.Geometry.sample_boundary	@wufei2 #833
53	ppsci.geometry.Geometry.sample_interior	@wufei2 #833
54	ppsci.geometry.Geometry.sdf_derivatives	@wufei2 #833
55	ppsci.geometry.Geometry.uniform_boundary_points	@wufei2 #833
56	ppsci.geometry.Geometry.uniform_points	@wufei2 #833
57	ppsci.geometry.Geometry.union	@wufei2 #833
58	ppsci.geometry.Mesh.from_pymesh	@smallpoxscattered #818
59	ppsci.geometry.Mesh.scale	@smallpoxscattered #818
60	ppsci.geometry.Mesh.translate	@smallpoxscattered #818
61	ppsci.geometry.PointCloud.translate	@wufei2 #839
62	ppsci.geometry.PointCloud.scale	@wufei2 #839
63	ppsci.geometry.PointCloud.random_boundary_points	@wufei2 #839
64	ppsci.geometry.PointCloud.random_points	@wufei2 #839
65	ppsci.geometry.PointCloud.uniform_points	@wufei2 #839
66	ppsci.geometry.TimeDomain.on_initial	@1want2sleep #829
67	ppsci.geometry.TimeXGeometry.uniform_points	@1want2sleep #829
68	ppsci.geometry.TimeXGeometry.random_points	@1want2sleep #829
69	ppsci.geometry.TimeXGeometry.uniform_boundary_points	@1want2sleep #829
70	ppsci.geometry.TimeXGeometry.random_boundary_points	@1want2sleep #829
71	ppsci.geometry.TimeXGeometry.uniform_initial_points	@1want2sleep #829
72	ppsci.geometry.TimeXGeometry.random_initial_points	@1want2sleep #829
73	ppsci.geometry.TimeXGeometry.periodic_point	@1want2sleep #829
74	ppsci.geometry.TimeXGeometry.sample_initial_interior	@1want2sleep #829
75	ppsci.loss.FunctionalLoss	@NKNaN #703
76	ppsci.loss.L1Loss	@NKNaN #701
77	ppsci.loss.L2Loss	@NKNaN #703
78	ppsci.loss.L2RelLoss	@NKNaN #703
79	ppsci.loss.MAELoss	@NKNaN #703
80	ppsci.loss.MSELoss	@NKNaN #703
81	ppsci.loss.MSELossWithL2Decay	@NKNaN #703
82	ppsci.loss.IntegralLoss	@NKNaN #703
83	ppsci.loss.PeriodicL1Loss	@NKNaN #703
84	ppsci.loss.PeriodicL2Loss	@NKNaN #703
85	ppsci.loss.PeriodicMSELoss	@NKNaN #703
86	ppsci.metric.FunctionalMetric	@NKNaN #723
87	ppsci.metric.MAE	@NKNaN #723
88	ppsci.metric.MSE	@NKNaN #723
89	ppsci.metric.RMSE	@NKNaN #723
90	ppsci.metric.L2Rel	@NKNaN #723
91	ppsci.metric.MeanL2Rel	@NKNaN #723
92	ppsci.solver.Solver.predict	@NKNaN #723
93	ppsci.utils.initializer.linear_init_	@NKNaN #730
94	ppsci.utils.initializer.conv_init_	@NKNaN #730
95	ppsci.utils.misc.PrettyOrderedDict	@NKNaN #730
96	ppsci.utils.misc.Prettydefaultdict	@NKNaN #730
97	ppsci.utils.misc.all_gather	@1want2sleep #840
98	ppsci.utils.misc.concat_dict_list	@NKNaN #730
99	ppsci.utils.misc.convert_to_array	@NKNaN #730
100	ppsci.utils.misc.convert_to_dict	@NKNaN #730
101	ppsci.utils.misc.stack_dict_list	@NKNaN #730
102	ppsci.utils.misc.combine_array_with_time	@NKNaN #730
103	ppsci.utils.misc.run_at_rank0	@ooooo-create #758
104	ppsci.utils.save_load.save_checkpoint	@ooooo-create #759
105	ppsci.utils.save_load.load_pretrain	@ooooo-create #759
106	ppsci.visualize.save_vtu_from_dict	@ooooo-create #762
107	ppsci.visualize.save_vtu_to_mesh	@ooooo-create #763
108	ppsci.visualize.save_plot_from_1d_dict	@ooooo-create #764
109	ppsci.visualize.save_plot_from_3d_dict	@ooooo-create #764

认领方式

请大家以 comment 的形式认领任务，如：

【报名】：1、3、12-13

多个任务之间需要使用中文顿号分隔，报名多个连续任务可用横线表示，如 2-5
PR 提交格式：在 PR 的标题中以 【PPSCI Doc No.xxx】 开头，注明任务编号

看板信息

任务方向	任务数量	提交作品 / 任务认领	提交率	完成	完成率
快乐开源	109	109 / 109	100.0%	109	100.0%

统计信息

排名不分先后 @Liyulingyue (9) @MayYouBeProsperous (5) @megemini (7) @Turingg (3) @1want2sleep (23) @WoWYoYLoL (3) @wufei2 (22) @smallpoxscattered (3) @NKNaN (27) @ooooo-create (7)

1. 背景

PaddleScience 目前有许多公开 API，通过 docstring 的方式给用户指示 API 功能简要描述，以及调用时涉及参数个数/类型、输出个数/类型，帮助用户更好地理解一个 API 的具体用法和使用场景。

具体地，一个好的 docstring 应该至少包含四个部分（按顺序排列，以 ppsci.utils.misc.cartesian_product为例）：

1. 函数功能简要说明

   

2. 输入参数描述

   

3. 返回值描述

   

4. 样例代码

   

文档最终在网页端的渲染效果如下:

但目前在 PaddleScience 中，有少量公开 API 的文档是缺少以上要素的，具体分为几种情况

1. 缺少参数、返回值描述、样例代码，如下所示

   

2. 缺少样例代码，如下所示

   

3. 样例代码不具有代表性，即无法告诉用户它的正确使用场景，仅仅说明了其最简单的调用方法

   

4. 文档格式不正确（如缺少换行）导致渲染失败

   

因此当用户在使用上述这些 API 时，可能无法快速、正确地知道它们能做什么以及在什么场景下使用，尤其是一部分实现较为复杂的 API，其理解成本会更高。最终导致开发的 API 因为无法被用户知悉而不被使用，既浪费了 API 开发的人力，也增加了用户自己实现的成本。

2. 收益

• 对于 PaddleScience 来说，完善 API 文档能显著减少用户的使用难度，增加 API 实际使用率，帮助用户更快地实现所需的功能。

• 对于参加本活动的开发者来说，可以学习以下三个方面的内容

  1. 如何编写一个好的 API 文档。
  2. 如何使用 doctest 插件对样例代码进行测试，让样例代码不仅能看，还能用于测试，保证 API 基本运行能力。
  3. 如何将 API 文档在项目文档中进行渲染，提升项目的规范性和可阅读性

3. 待完善的 API 文档

参考文档开头的表格

4. 开发流程

4.1. 撰写

1. 文档要素缺失的情况具体该如何补全呢？

   • 缺少参数、返回值类型的，补全参数和返回值类型；
   • 缺少样例代码的，补全具有代表性的样例代码；
   • 格式不正确的，修正格式；

2. 样例代码如何撰写？

   • 样例代码撰写方法与 python 交互式命令相同，以 >>> 的一行代码会直接执行，以 ...开头的代码与 >>> 区分，并不会马上执行，而是会等到下一个 >>> 或者代码块结束，与中间遇到的所有代码组成完整的代码再执行，一般用于带缩进的代码结构，如 for、while、函数调用等完整代码块超过一行的情况。

3. 有的 API 样例代码并不会产生任何输出，该如何进行检查？

   • 若用 doctest 对样例代码的输出结果进行检查，则可以将期望的结果粘贴在代码结束后，如下所示。这种情况常见于计算类的 API。
     doctest 会自动将打印的txy与红框中的值进行比较，如果不一致则会报错。
   • 若被 doctest 检查的代码并不具有输出值，即属于跑通就算测试通过的情况，则不需要在末尾粘贴期望结果，如下所示。这种情况常见于装饰器等辅助类 API

4.2. doctest 测试

首先安装 doctest，执行：pip install pydoctest==0.1.22

然后运行 doctest并测试指定文件，执行：python -m doctest xxxx.py，如测试未通过则需要重新修改案例代码直至通过。此处 xxx.py 是你修改后的 docstring 所在的代码文件路径（建议使用绝对路径）。

4.3. 文档渲染

文档渲染基本原理：项目文档渲染依赖于 mkdocs、mkdocs-material，而其中的 API 文档涉及到代码引用（避免维护python和文档两份代码，而是直接从 python 文件中抽取对应位置的代码展示在网页前端）功能，依赖于 mkdocstrings 插件（可以在 PaddleScience/mkdocs.yml中找到相关配置）。

1. 安装文档依赖：pip install docs/requirements.txt
2. 在 PaddleScience/ 目录下执行： mkdocs serve -a 127.0.0.1:8687。等待终端渲染完毕，打印出预览地址，在网页端打开并进入 【API 文档】中找到自己修改的内容，即可预览修改效果。如下所示
   

4.4. 代码提交

Important

PR 标题模板：【PPSCI Doc No.{id}】，如 【PPSCI Doc No.66】
代码内容提交请参考：https://paddlescience-docs.readthedocs.io/zh/latest/zh/development/#4 【整理代码并提交】章节

5. 参考资料

• https://www.mkdocs.org/
• https://squidfunk.github.io/mkdocs-material/
• https://mkdocstrings.github.io/
• https://docs.python.org/3/library/doctest.html

[MayYouBeProsperous]

【报名】：10、11、30

[megemini]

【报名】：12、13、14、15、16、17