Polish documents for fluid operators.

[pkuyym]

We have to polish the documents for fluid operators. This issue takes fc as an example to show the documentation specification.

python/paddle/v2/fluid/layers.py#fc

def fc(input,
       size,
       num_flatten_dims=1,
       param_attr=None,
       bias_attr=None,
       act=None,
       name=None,
       main_program=None,
       startup_program=None):
    """Fully Connected Layer. This layer accepts multiple inputs and applies
    linear transformation to each input data. If activation type provided,
    corresponding nonlinear transformation would be applied then. For each input
    :math:`X`, the equation is:

    .. math::

        Out = Act(WX + b)

    In the above equation:

        * :math:`X`: Input value, a tensor with rank at least 2.
        * :math:`W`: Weight, a 2-D tensor with shape [M, N].
        * :math:`b`: Bias, a 2-D tensor with shape [M, 1].
        * :math:`Act`: Activation function.
        * :math:`Out`: Output value, same shape with :math:`X`.

    All the input variables are passed in as local variables to the LayerHelper
    constructor.

    Args:
        Input (Variable|list): The input values, each value is a tensor with
            rank at least 2.
        size (int): The output size, an interge value.
        num_flatten_dims (int): Column number of the input.
        param_attr (ParamAttr|list): The parameters/weights to the FC Layer.
        bias_attr (ParamAttr|list): The bias parameter.
        act (str): Activation type.
        name (str): Name/alias of the function.
        main_program (Program): The main program calling this.
        startup_program (Program): The startup program.

    Returns:
        Variable: The tensor variable storing the transformation and \
                  non-linearity activation result.

    Raises:
        ValueError: If rank of input tensor is less than 2.

    Examples:
        .. code-block:: python

          data = fluid.layers.data(name='data', shape=[32, 32], dtype='float32')
          fc = fluid.layers.fc(input=data, size=1000, act="tanh")
    """

And the final html looks like:

How to preview

After refined the documents in layers.py, we need to preview the html page. Here I list some key tips:

1. Go to build directory.
2. Please make sure WITH_DOC=1 and sphinx==1.5.6.
3. make -j `nproc` && python -m SimpleHTTPServer $PORT_NUM
4. Assume that PaddlePaddle is compiled on computer with ip being $IP. We can visit $IP:$PORT_NUM/doc/en/html/api/v2/fluid/layers.html to check the preview.
5. Add link in doc/api/v2/fluid/layers.rst

URLs

Docs of sphnix: http://www.sphinx-doc.org/en/stable/contents.html
How to insert codes: http://www.sphinx-doc.org/en/stable/markup/code.html
How to insert math equations: http://www.sphinx-doc.org/en/stable/ext/math.html
Previous discussion: #6160

Operators need to polish

Please create an issue first before do polishing.

• fc @pkuyym @abhinavarora Polishing the embedding layer and the fc layer documentation #6806
• embedding @qingqing01 @abhinavarora Polishing the embedding layer and the fc layer documentation #6806
• dynamic_lstm @kuke Add python doc for dynamic_lstm #7640
• gru_unit @sidgoyal78
• data @kavyasrinet Polish docs for data layer #6858
• concat @NHZlX @abhinavarora Polish API docs for Fluid Assign and Concat layer #6855
• sums @wanghaoshuang @kavyasrinet Adding documentation for sums layer #6857
• linear_chain_crf @lcy-seso
• assign @abhinavarora Polish API docs for Fluid Assign and Concat layer #6855
• split_lod_tensor @kavyasrinet Addign document for fluid split_lod_tensor and merge_lod_tensor #6859
• merge_lod_tensor @kavyasrinet Addign document for fluid split_lod_tensor and merge_lod_tensor #6859
• cos_sim @lcy-seso
• cross_entropy @kuke Polish the doc of cross_entropy_op #7018
• square_error_cost @sidgoyal78 Add squared error layers doc #6862
• accuracy @wanghaoshuang Fix doc of accuracy function #7091
• sequence_conv
• conv2d @chengduoZH Add conv2d_python doc #6850
• sequence_pool @luotao1 Need add python wrapper for sequence_pool #6777
• pool2d @NHZlX
• batch_norm @sidgoyal78
• beam_search_decode
• lstm
• lod_rank_table @pkuyym Add doc for lod_rank_table #7024
• max_sequence_len @pkuyym Add doc for max_sequence_len #7023
• topk @kavyasrinet Added documentation for topk layer fluid. #6861
• lod_tensor_to_array @kavyasrinet Adding documentation for the operators: lod_tensor_to_array , array_to_lod_tensor, create_array, increment #6807
• array_to_lod_tensor @kavyasrinet Adding documentation for the operators: lod_tensor_to_array , array_to_lod_tensor, create_array, increment #6807
• fill_constant @abhinavarora ebe4425
• fill_constant_batch_size_like @abhinavarora ebe4425
• ones @abhinavarora Adding API docs for ones and zeros methods #7150
• zeros @abhinavarora Adding API docs for ones and zeros methods #7150
• increment @kavyasrinet Adding documentation for the operators: lod_tensor_to_array , array_to_lod_tensor, create_array, increment #6807
• array_write @kavyasrinet Writeup for array write layer #6820
• create_array @kavyasrinet Adding documentation for the operators: lod_tensor_to_array , array_to_lod_tensor, create_array, increment #6807
• less_than @abhinavarora Polishing the documentation of the less than layer #6816
• array_read @kavyasrinet Adding array read layer documentattion #6853
• shrink_memory
• array_length @kavyasrinet Adding documentation for the layer: array_length #6817
• conv2d_transpose @chengduoZH Refine conv2d_transpose layer doc #6920
• seq_expand @pkuyym Need add python wrapper for SeqExpandOp. #6590
• lstm_unit @pkuyym Need add python wrapper for 'lstm_unit' op #6581
• reduce_sum @guoshengCS
• reduce_mean @guoshengCS
• reduce_max @guoshengCS
• reduce_min @guoshengCS

[luotao1]

Do we refine http://www.paddlepaddle.org/docs/develop/documentation/en/operators.html as well ?
Or only consider http://www.paddlepaddle.org/docs/develop/documentation/en/api/v2/fluid/layers.html ?
These two htmls are duplicated in most cases.

[abhinavarora]

@luotao1 We have already refactored the latex equations and the English grammar in the operator docs in this project (https://github.com/PaddlePaddle/Paddle/projects/31).
The next step that we have is to write components of the operator documentation in Markdown. I will add tasks for these in the above project. Please feel free to add new ToDo items to the project for the same. Thank you.

[pkuyym]

@abhinavarora @luotao1 Users have to refer layers.html when creating models using fluid, so I think refining of documents for python wrappers has the highest priority. Of course, other documents are also necessary and we can polish them one by one.

[abhinavarora]

@pkuyym I agree with you. Lets focus on this right now

[luotao1]

@pkuyym I am confused that should we keep the documents same between operators.html and layers.html, should we just only do copy and paste?

[abhinavarora]

@luotao1 I think both of them are different documents and both of them are targeted for different users. operators.html is document for C++ ops and end users will not be using this directly. That document is more useful for people who want to contribute to paddlepaddle or dive into more details. On the other hand layers.html is document for Python layers API. This will be directly used by end users who build python models. A layer can be a bunch of c++ operators combined. Hope this explanation helps.

[abhinavarora]

@pkuyym @lcy-seso @luotao1 @qingqing01 @kuke @chengduoZH @NHZlX We all should wait for @reyoung to merge #6564 before making more changes for this issue. He is working on this PR to split layers.py to many files, since layers.py is too large. We should wait to begin new PRs, otherwise his task of merging will become very difficult.

[luotao1]

@abhinavarora I agree with you!
But can you give an example for two different documents. I wonder how to write them for different target users.

[pkuyym]

@luotao1 I'm targeting to refine the documentation for layers.html and please refer the example in above comment. For documentation of operators, I think it's also sphinx format and we can discuss about the specification.

[kavyasrinet]

I have the same question as @luotao1 , I looked at the PR, and I still don't understand what the difference between the documentations of layers.html and operators.html would be. I had written the documentation for each operator in layers.py, in the past here : https://github.com/PaddlePaddle/Paddle/pull/5529/files , before we replaced the framework directory with fluid. Maybe we can re-use this and add on top of it.

[luotao1]

@pkuyym Your example is fc, which doesn't have op in C++. But I am confused how to write two versions of sequence_pool_op.

@abhinavarora I agree with @kavyasrinet , maybe it's difficult for developers to write and maintain two versions of an same op.

If layer=op, why we should rewrite a different doc version?

[kavyasrinet]

Hi @pkuyym can you please edit the above documentation to explain how to set up the preview when using docker to build, when we follow this documentation: https://github.com/PaddlePaddle/Paddle/blob/develop/doc/howto/dev/build_en.md

[luotao1]

@kavyasrinet May be this file http://www.paddlepaddle.org/docs/develop/documentation/en/howto/dev/write_docs_en.html can help you. But this file should be updated since something is wrong.

[kavyasrinet]

Thanks for pointing that out @luotao1 . But I was mostly asking about -- when building PaddlePaddle using Docker using the document mentioned here: https://github.com/PaddlePaddle/Paddle/blob/develop/doc/howto/dev/build_en.md . I am not sure how to enable the mentioned flags for enabling documentation. We should update the file above to address this as well.

[luotao1]

@kavyasrinet The flag is cmake .. -DWITH_DOC=ON
https://github.com/PaddlePaddle/Paddle/blob/develop/doc/getstarted/build_and_install/build_from_source_en.rst#bool-type-options

build_en.md will updated into build_from_source_en.rst as #6311 (comment) mentioned

[abhinavarora]

@luotao1 Sorry, I forgot to reply to your previous comment. I think the reason we need 2 docs is because layer is not equal to operator. A layer is a Python wrapper that consists of 1 or more operators. In some operators, there is one to one correspondence between layers and operators, but that will not be true always.

Also since PaddlePaddle, is an open source project, we need a separate documentation for Operators because some users might prefer to fork PaddlePaddle and then write some new layers which are specific to their use case.

[luotao1]

As we have API doc standard and a list of API doc jobs now, this issue could be closed.