Don't map operator name to Python functions

[wangkuiyi]

def __bootstrap__():
    """
    Bootstrap function for this module. It will dynamic create all op creation
    methods in runtime.
    """
    for op_proto in get_all_op_protos():
        func = create_op_creation_method(op_proto)
        func.__name__ = str(op_proto.type)
        setattr(op_creations, func.__name__, func)

This introduces extra complexity compared with

core.operator("ReLU", input={...}, output={...})

The former approach would create confusion for our users -- users might see a call in an example program like fc(...) but s/he cannot grep the codebase to find the definition of function fc.

[reyoung]

What argument should core.operator() method take?

Should it be

core.operator("Mul", input={
  "A": "var_a",
  "B": "var_b"
}, output={
  "Out": "var_out"
}, attr={
  "some_attr": 1.0,
  "other_attr": [1,2,3,4]
})

or

core.operator("Mul", A="var_a", B="var_b", Out="var_out", some_attr=1.0, other_attr=[1,2,3,4])

Also, what reference documentation of operator should be? Currently, op_creations.xxx generate the docstring from Paddle C++ core. Like

>> help(op_creations.add_two)

Help on function add_two in module paddle.v2.framework.create_op_creation_methods:

add_two(*args, **kwargs)
    Two Element Add Operator.

    The equation is: Out = X + Y

    :param X: The first input of add op
    :type X: basestr
    :param Y: The second input of add op
    :type Y: basestr
    :param Out: The output of add op
    :type Out: basestr

[wangkuiyi]

Either API call in your case @reyoung looks good to me.

My point is that the primary document of source code is the source code itself.

I understand that a Python wrapper like fc to operator("fc", ...) is cleaner, but to be consistent with above rule, we'd like to have def fc(...) somewhere in our codebase. We could generate this Python function definition by a code-generator.

[reyoung]

Either API call in your case @reyoung looks good to me.

OK. I will choose the second API in implementation because it seems that less code for the user.

I don't see it's super valuable using Python's help to retrieve documentation. The most straightforward document is the code itself. The most intuitive ways is a documentation HTML page, which can be generated from C++ source code.

Python docstring can generate HTML pages, i.e., API reference page by Sphinx. It is a common way for Python code/API.

I agree that the most straight-forward document is code itself. But for end-user, a HTML pages is necessary. In this way we do not generate function to each operator, we must figure out how to generate a HTML file from C++ operator.

Maybe to generate an markdown file for each operator is OK? I will add other issue for operator documentation generating when the second API is done.

[wangkuiyi]

I think we need documents for two levels of API

1. Operators. Because operators are defined as C++ classes, we should generate its documentation from C++ source code. This level of documentation is for layer developers, and doesn't have to be visitable through Pythons' help function.

2. Layers. Because layers are Python functions, we should generate their documentation from the Python source code. This documentation is for application developers, and should be exposed via Python's help function.

Both levels of documentation can have HTML format.

[reyoung]

@wangkuiyi I am working on this issue #3169 today. I will change the Python API tomorrow.