Dev add docstring (#5449)

* startup: use python, not C extension

* rst changes test

* refine

* add F.rst

* add bernoulli add docstr example

* add doctest for functional method

* del docstr utils immediately in init.py

* refine test case

* use sin, cos instead of add, mul

* refine

Co-authored-by: oneflow-ci-bot <69100618+oneflow-ci-bot@users.noreply.github.com>

docs/source/F.rst

+oneflow.F
+===================================
+Functional functions
+----------------------------------
+.. currentmodule:: oneflow.F
+.. autofunction:: oneflow.F.bernoulli
+.. autofunction:: oneflow.F.cos
+.. autofunction:: oneflow.F.sin

docs/source/index.rst

@@ -26,6 +26,7 @@ OneFlow API Reference
     tensorrt 
     deprecated  
     experimental 
+    F
     scope 
     sysconfig    
     random 

oneflow/init.py

@@ -128,3 +128,10 @@ if not oneflow._oneflow_internal.IsMultiClient():
 
 del absolute_import
 del oneflow
+
+import oneflow.python.framework.docstr as docstr
+from oneflow.python.framework.docstr.utils import register_docstr
+
+register_docstr()
+del register_docstr
+del docstr

oneflow/python/framework/docstr/__init__.py

+"""
+Copyright 2020 The OneFlow Authors. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+from .math_ops import *
+from .random import *

oneflow/python/framework/docstr/math_ops.py

+"""
+Copyright 2020 The OneFlow Authors. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+import oneflow
+from oneflow.python.framework.docstr.utils import add_docstr
+
+add_docstr(
+    oneflow.F.sin,
+    r"""
+    sin(x: Tensor) -> Tensor
+
+    Returns a new tensor with the sine of the elements of :attr:`input`.
+
+    .. math::
+
+        \text{y}_{i} = \sin(\text{x}_{i})
+
+    Args:
+        x (Tensor): the input tensor.
+
+    For example:
+
+    .. code-block:: python
+
+        >>> import oneflow.experimental as flow
+        >>> import numpy as np
+        >>> flow.enable_eager_execution()
+        >>> x1 = flow.Tensor(np.array([-0.5461,  0.1347, -2.7266, -0.2746]).astype(np.float32))
+        >>> y1 = flow.F.sin(x1)
+        >>> y1
+        tensor([-0.5194,  0.1343, -0.4032, -0.2712], dtype=oneflow.float32)
+        >>> x2 = flow.Tensor(np.array([-1.4, 2.6, 3.7]).astype(np.float32),device=flow.device('cuda'))
+        >>> y2 = flow.F.sin(x2)
+        >>> y2
+        tensor([-0.9854,  0.5155, -0.5298], device='cuda:0', dtype=oneflow.float32)
+
+
+""",
+)
+
+add_docstr(
+    oneflow.F.cos,
+    r"""
+    cos(x: Tensor) -> Tensor
+
+    Returns a new tensor with the cosine  of the elements of :attr:`input`.
+    
+    .. math::
+        \text{y}_{i} = \cos(\text{x}_{i})
+
+    Args:
+        x (Tensor): the input tensor.
+
+    For example:
+
+    .. code-block:: python
+
+        >>> import oneflow.experimental as flow
+        >>> import numpy as np
+        >>> flow.enable_eager_execution()
+        >>> x = np.array([1.4309,  1.2706, -0.8562,  0.9796])
+        >>> x = flow.Tensor(x, dtype=flow.float32)
+        >>> y = flow.F.cos(x)
+        >>> y
+        tensor([0.1394, 0.2957, 0.6553, 0.5574], dtype=oneflow.float32)
+
+""",
+)

oneflow/python/framework/docstr/random.py

+"""
+Copyright 2020 The OneFlow Authors. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+import oneflow
+from oneflow.python.framework.docstr.utils import add_docstr
+
+add_docstr(
+    oneflow.F.bernoulli,
+    r"""
+    bernoulli(input, *, generator=None, out=None)
+    
+    This operator returns a Tensor with binaray random numbers (0 / 1) from a Bernoulli distribution.
+
+    Args:
+        input (Tensor): the input tensor of probability values for the Bernoulli distribution
+        generator: (Generator, optional) a pseudorandom number generator for sampling
+        out (Tensor, optional): the output tensor.
+
+    Shape:
+        - Input: :math:`(*)`. Input can be of any shape
+        - Output: :math:`(*)`. Output is of the same shape as input
+
+    For example:
+
+    .. code-block:: python
+
+        >>> import numpy as np
+        >>> import oneflow.experimental as flow
+        >>> flow.enable_eager_execution()
+
+        >>> arr = np.array(
+        ...    [
+        ...        [1.0, 1.0, 1.0],
+        ...        [1.0, 1.0, 1.0],
+        ...        [1.0, 1.0, 1.0],
+        ...    ]
+        ... )
+        >>> x = flow.Tensor(arr)
+        >>> y = flow.F.bernoulli(x)
+        >>> y
+        tensor([[1., 1., 1.],
+                [1., 1., 1.],
+                [1., 1., 1.]], dtype=oneflow.float32)
+
+    """,
+)

oneflow/python/framework/docstr/utils.py

+"""
+Copyright 2020 The OneFlow Authors. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+_function_docstr = {}
+
+
+def add_docstr(fun, docstr: str):
+    _function_docstr[fun] = docstr
+
+
+def register_docstr():
+    for fun, docstr in _function_docstr.items():
+        setattr(fun, "__doc__", docstr)

oneflow/python/test/modules/test_functional_docstr.py

+"""
+Copyright 2020 The OneFlow Authors. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+import unittest
+import inspect
+from collections import OrderedDict
+
+import oneflow as flow
+from oneflow.python.framework.functional import Function
+from test_util import GenArgList
+
+
+def _is_oneflow_functional(object):
+    return isinstance(object, Function)
+
+
+def _run_functional_doctest(
+    test_case,
+    globs=None,
+    verbose=None,
+    optionflags=0,
+    raise_on_error=True,
+    module=flow.F,
+):
+    import doctest
+
+    parser = doctest.DocTestParser()
+    if raise_on_error:
+        runner = doctest.DebugRunner(verbose=verbose, optionflags=optionflags)
+    else:
+        runner = doctest.DocTestRunner(verbose=verbose, optionflags=optionflags)
+
+    r = inspect.getmembers(flow.F, _is_oneflow_functional)
+    for name, fun in r:
+        if (
+            fun.__doc__ is not None
+        ):  # TODO(yaochi) None value of __doc__ will not be allowed
+            print("test on docstr of: ", ".".join([module.__name__, name]))
+            test = parser.get_doctest(fun.__doc__, {}, __name__, __file__, 0)
+            runner.run(test)
+
+
+@unittest.skipIf(
+    not flow.unittest.env.eager_execution_enabled(),
+    ".numpy() doesn't work in lazy mode",
+)
+class TestFunctionalDocstrModule(flow.unittest.TestCase):
+    def test_functional_docstr(test_case):
+        arg_dict = OrderedDict()
+        arg_dict["module"] = [flow.F, flow.experimental.F]
+        for arg in GenArgList(arg_dict):
+            _run_functional_doctest(
+                test_case, raise_on_error=True, verbose=None, module=arg[0]
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()