【快乐开源】科学计算 API 文档补全 #686
Description
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为例）：
-
函数功能简要说明
-
输入参数描述
-
返回值描述
-
样例代码
文档最终在网页端的渲染效果如下:
但目前在 PaddleScience 中，有少量公开 API 的文档是缺少以上要素的，具体分为几种情况
-
缺少参数、返回值描述、样例代码，如下所示
-
缺少样例代码，如下所示
-
样例代码不具有代表性，即无法告诉用户它的正确使用场景，仅仅说明了其最简单的调用方法
-
文档格式不正确（如缺少换行）导致渲染失败
因此当用户在使用上述这些 API 时，可能无法快速、正确地知道它们能做什么以及在什么场景下使用，尤其是一部分实现较为复杂的 API，其理解成本会更高。最终导致开发的 API 因为无法被用户知悉而不被使用，既浪费了 API 开发的人力，也增加了用户自己实现的成本。
2. 收益
-
对于 PaddleScience 来说，完善 API 文档能显著减少用户的使用难度，增加 API 实际使用率，帮助用户更快地实现所需的功能。
-
对于参加本活动的开发者来说，可以学习以下三个方面的内容
- 如何编写一个好的 API 文档。
- 如何使用 doctest 插件对样例代码进行测试，让样例代码不仅能看，还能用于测试，保证 API 基本运行能力。
- 如何将 API 文档在项目文档中进行渲染，提升项目的规范性和可阅读性
3. 待完善的 API 文档
参考文档开头的表格
4. 开发流程
4.1. 撰写
-
文档要素缺失的情况具体该如何补全呢？
- 缺少参数、返回值类型的，补全参数和返回值类型；
- 缺少样例代码的，补全具有代表性的样例代码；
- 格式不正确的，修正格式；
-
样例代码如何撰写？
- 样例代码撰写方法与 python 交互式命令相同，以
>>>的一行代码会直接执行，以...开头的代码与>>>区分，并不会马上执行，而是会等到下一个>>>或者代码块结束，与中间遇到的所有代码组成完整的代码再执行，一般用于带缩进的代码结构，如 for、while、函数调用等完整代码块超过一行的情况。
- 样例代码撰写方法与 python 交互式命令相同，以
-
有的 API 样例代码并不会产生任何输出，该如何进行检查？
- 若用 doctest 对样例代码的输出结果进行检查，则可以将期望的结果粘贴在代码结束后，如下所示。这种情况常见于计算类的 API。
doctest 会自动将打印的txy与红框中的值进行比较，如果不一致则会报错。 - 若被 doctest 检查的代码并不具有输出值，即属于跑通就算测试通过的情况，则不需要在末尾粘贴期望结果，如下所示。这种情况常见于装饰器等辅助类 API
- 若用 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中找到相关配置）。
- 安装文档依赖：
pip install docs/requirements.txt - 在
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. 参考资料
Metadata
Metadata
Assignees
Labels
Type
Projects
Status