Add api doc std #8927

ranqiu92 · 2018-03-09T09:01:36Z

luotao1

整体标准定义的很不错，文档描述上还需进一步完善。
需要强调api注释是使用rst格式来写，参考链接：http://sphinx-doc-zh.readthedocs.io/en/latest/rest.html

luotao1 · 2018-03-12T03:20:47Z

doc/fluid/dev/api_doc_std_cn.md

+
+API文档各模块格式及示例如下：
+
+### Python API Definition & Python Wrapper Location


49行是12行+16行，如果前面分开列了，这儿也要分开列。两者需要统一。

前面使用-，这儿使用###，需要统一使用-。51行和57行的-进行缩进。改成rst文件后，这儿的格式也需要略作调整。

luotao1 · 2018-03-12T03:21:34Z

doc/fluid/dev/api_doc_std_cn.md

+
+  - 示例
+
+    #### [fluid.layers.fc](https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/fluid/layers/nn.py)


这里的链接是到nn.py，并不是直接到fc

示例的链接：请使用以下方法，将md文件改成rst文件，然后将完整的注释拿出来专门做一个.py文件，放在同目录下的src子目录下。引用方式参考：
https://github.com/PaddlePaddle/Paddle/blob/develop/doc/v2/howto/rnn/hrnn_rnn_api_compare_cn.rst

.. literalinclude:: ../../../../paddle/gserver/tests/sequenceGen.py :language: python :lines: 42-71 :linenos:

来一一说明每行对应哪个格式。

是否要考虑行数发生变化的情况？感觉随着api的丰富，对应的行可能会发生变化

对于一个专门的示例py文件来说，它是不会随着api的丰富而发生变化的。

luotao1 · 2018-03-12T03:22:57Z

doc/fluid/dev/api_doc_std_cn.md

+	   name=None,
+	   main_program=None,
+	   startup_program=None)
+  ```


61-69行是说明什么呢？可以在47行加上：以fc为例来进行说明？

[Python API Definition]

luotao1 · 2018-03-12T03:24:12Z

doc/fluid/dev/api_doc_std_cn.md

+
+  - 格式：
+
+    [Python API Name][Python Wrapper URL]


Python Wrapper URL的示例是在哪儿？需要对每个[]内容都有示例。

Python Wrapper URL的示例能否做成自动生成，如果做不到的话，就不要列了。后期维护会很麻烦。

luotao1 · 2018-03-12T03:25:38Z

doc/fluid/dev/api_doc_std_cn.md

+
+    [Formula]
+
+    [Symbols' Descriptions if necessary]


需要对每个[]的示例进行说明，我理解85行是Function Description，86行是Formula，87行是Symbols' Descriptions，需要再强调说一下

luotao1 · 2018-03-12T03:27:04Z

doc/fluid/dev/api_doc_std_cn.md

+
+  - 示例
+
+    以dynamic_lstm为例


全文的示例能否统一，上文是fc，这儿是dynamic_lstm，能否统一？

原本是想演示下当返回值为多个的情况怎么写

可以进行演示，选一个好点的api示例即可。

luotao1 · 2018-03-12T03:27:22Z

doc/fluid/dev/api_doc_std_cn.md

+  - 示例
+
+  ```
+  ```


请加示例

luotao1 · 2018-03-12T03:31:46Z

doc/fluid/dev/api_doc_std_cn.md

+
+```python
+  data = fluid.layers.data(name='data', shape=[1], dtype='float32')
+  fc = fluid.layers.fc(input=data, size=10, act="tanh")


fc的注释不只你列出来的，可以使用rst文档的literalinclude来完整引入（上面评论中有写）。

没太明白这句话，这里fc的注释还缺什么？

http://www.paddlepaddle.org/docs/develop/api/en/fluid/layers.html#fc 看注释内容非常多，你列出来的每一项都不全。

luotao1 · 2018-03-12T03:38:54Z

doc/fluid/dev/api_doc_std_cn.md

@@ -0,0 +1,203 @@
+# API文档撰写


API注释撰写标准

luotao1 · 2018-03-12T03:39:04Z

doc/fluid/dev/api_doc_std_cn.md

@@ -0,0 +1,203 @@
+# API文档撰写
+
+- [API文档模块](#API文档模块)


API注释模块

luotao1

请对应更新src/fc.py的注释和nn.py里面fc的注释。

luotao1 · 2018-03-13T11:52:36Z

doc/fluid/dev/api_doc_std_cn.md

+
+## 完整示例
+
+fc 的完整注释见[示例](https://github.com/PaddlePaddle/Paddle/tree/develop/doc/fluid/dev/src/fc.py)。


链接使用相对路径，现在的路径访问不了。
[示例](src/fc.py)

luotao1 · 2018-03-13T11:53:48Z

doc/fluid/dev/api_doc_std_cn.md

+
+  - 示例
+
+      fc没有注意事项，故该模块省略不写。其他情况应明确给出，若有多条注意事项，须分条列出，以scaled\_dot\_product\_attention为例：


其他情况指哪些情况？改成：如有注意事情应明确给出？

luotao1 · 2018-03-13T11:58:52Z

doc/fluid/dev/api_doc_std_cn.md

+
+      ```
+      Args:
+          input (Tensor): The input tensor(s) of the layer.


input这个注释需要修改

原来也有list类型给漏掉了。(Variable|list) – The input tensor(s) to the fully connected layer.

这个tensor是几维的。

input和output都是Variable，variable里面是XX维的tensor

luotao1 · 2018-03-13T12:09:30Z

doc/fluid/dev/api_doc_std_cn.md

+
+## 格式及示例
+
+API文档各模块格式及示例如下(以下以fc为例进行说明）：


43行的括号需要改完中文括号。

luotao1 · 2018-03-13T12:11:14Z

doc/fluid/dev/api_doc_std_cn.md

+- [完整示例](#完整示例)
+
+
+## API注释模块


需要强调api注释文档是使用rst格式来写，有关rst格式的参考链接：http://sphinx-doc-zh.readthedocs.io/en/latest/rest.html
请组织语言。

luotao1 · 2018-03-14T02:49:29Z

doc/fluid/dev/api_doc_std_cn.md

@@ -40,7 +40,7 @@ API文档须包含以下几个模块（排列顺序为文档撰写顺序）：

 ## 格式及示例

-API文档各模块格式及示例如下(以下以fc为例进行说明）：
+API文档须使用rst格式撰写，该格式详情请参考[链接](http://sphinx-doc-zh.readthedocs.io/en/latest/rest.html)。API文档各模块的内容格式及示例如下（以下以fc为例进行说明）：


rst->reStructuredText

luotao1 · 2018-03-14T02:51:23Z

doc/fluid/dev/api_doc_std_cn.md

@@ -137,7 +137,7 @@ API文档各模块格式及示例如下(以下以fc为例进行说明）：

      ```
      Args:
-          input (Tensor): The input tensor(s) of the layer.
+          input (Variable|list of Variable): This layer's input tensor(s) which is at least 2-dimensional.


The input tensor(s) of the layer, and the dimension of the input tensor(s) is at least 2.

luotao1

LGTM! Thanks very much!

ranqiu92 requested review from lcy-seso and luotao1 March 9, 2018 09:01

luotao1 reviewed Mar 12, 2018

View reviewed changes

luotao1 mentioned this pull request Mar 13, 2018

Record links of all .md files in the fluid directory #8976

Closed

Add api doc std

686a3ad

luotao1 reviewed Mar 13, 2018

View reviewed changes

Refine api_doc_std_cn

a78b760

luotao1 reviewed Mar 14, 2018

View reviewed changes

Update api doc std and fc doc

fc0f92c

luotao1 approved these changes Mar 14, 2018

View reviewed changes

luotao1 merged commit ad6b59e into PaddlePaddle:develop Mar 14, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add api doc std #8927

Add api doc std #8927

ranqiu92 commented Mar 9, 2018 •

edited by luotao1

Loading

luotao1 left a comment

luotao1 Mar 12, 2018

luotao1 Mar 12, 2018

ranqiu92 Mar 12, 2018

luotao1 Mar 12, 2018

luotao1 Mar 12, 2018

ranqiu92 Mar 12, 2018

luotao1 Mar 12, 2018

ranqiu92 Mar 12, 2018

luotao1 Mar 12, 2018

luotao1 Mar 12, 2018

luotao1 Mar 12, 2018

ranqiu92 Mar 12, 2018 •

edited

Loading

luotao1 Mar 12, 2018

luotao1 Mar 12, 2018

luotao1 Mar 12, 2018

ranqiu92 Mar 12, 2018

luotao1 Mar 12, 2018

luotao1 Mar 12, 2018

luotao1 Mar 12, 2018

luotao1 left a comment

luotao1 Mar 13, 2018

luotao1 Mar 13, 2018

luotao1 Mar 13, 2018

luotao1 Mar 13, 2018

luotao1 Mar 13, 2018

ranqiu92 Mar 14, 2018

luotao1 Mar 14, 2018

ranqiu92 Mar 14, 2018

luotao1 Mar 14, 2018

ranqiu92 Mar 14, 2018

luotao1 left a comment


		API文档各模块格式及示例如下：

		### Python API Definition & Python Wrapper Location


		- 示例

		#### [fluid.layers.fc](https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/fluid/layers/nn.py)

+                - 示例
+                ```
+                ```

		@@ -0,0 +1,203 @@
		# API文档撰写

		- [API文档模块](#API文档模块)


		## 完整示例

		fc 的完整注释见[示例](https://github.com/PaddlePaddle/Paddle/tree/develop/doc/fluid/dev/src/fc.py)。


		- 示例

		fc没有注意事项，故该模块省略不写。其他情况应明确给出，若有多条注意事项，须分条列出，以scaled\_dot\_product\_attention为例：


		## 格式及示例

		API文档各模块格式及示例如下(以下以fc为例进行说明）：

Add api doc std #8927

Add api doc std #8927

Conversation

ranqiu92 commented Mar 9, 2018 • edited by luotao1 Loading

luotao1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ranqiu92 Mar 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

luotao1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

luotao1 left a comment

Choose a reason for hiding this comment

ranqiu92 commented Mar 9, 2018 •

edited by luotao1

Loading

ranqiu92 Mar 12, 2018 •

edited

Loading