Improve docs of functions and links

(Last update: 23 August, 2017)

About

This is a part of documentation improvement. This issue is about API document, in particular, functions and links. Contributions are welcomed! If you have any questions, please feel free to comment in this issue. See also: #1867

Current document

Functions: http://docs.chainer.org/en/stable/reference/functions.html Links: http://docs.chainer.org/en/stable/reference/links.html

How to contribute

Before modifying files, please see http://docs.chainer.org/en/stable/contribution.html#coding-guidelines . For really lazy guys, you need to run below commands to confirm your codes following the coding guideline!

autopep8 --global-config .pep8 path/to/your/code.py
flake8 path/to/your/code.py

Preparation

Set the developer mode for chainer.

1. Type pip uninstall chainer multiple times, until you see the error of Cannot uninstall requirement chainer, not installed.
2. Go to your (forked-and-cloned) chainer working directory.
3. Type python setup.py develop. Now you can use import chainer in the python.

Modification

Please see each function/link template and how-to described in the latter part of this issue.

Notation rule

We are now creating notation rules in the comment of this issue! Please see: https://github.com/pfnet/chainer/issues/2182#issuecomment-275901211

Test on your local machine

1. Run doctest After modifying the files, you need to run doctest before sending PRs, using sphinx (please pip install sphinx for the first time). To test only one file, you need to add these lines at the end of the file you modified, and type python FILENAME.

if __name__ == "__main__":
    import doctest
    import numpy as np
    # import cupy  # comment out if you don' have GPU
    import chainer
    from chainer import cuda, Function, gradient_check, training, utils, Variable
    from chainer import datasets, iterators, optimizers, serializers
    from chainer import Link, Chain, ChainList
    import chainer.functions as F
    import chainer.links as L
    from chainer.training import extensions
    np.random.seed(0)
    doctest.testmod()

1. Confirm compiled files Make sure to delete these parts after the doctest! If the codes passes it, then you can compile the documentation and see the result.

cd docs
make html

Now you can access the compiled documentations in your browser (e.g. google chrome). URL is:

file://PATH-TO-YOUR-CHAINER-DIRECTORY/docs/build/html/index.html

Please check your modification seems good!

1. (Optional) Run doctest for all the documentations To test whole the documentation, you need GPU environment currently. On command line: cd docs; make doctest

Pull Requests

Please make sure your codes passed doctest, autopep8, and flake8 again. PRs can be made for each function or links, or for several functions at one PR (for example, #2208 ). Template of PRs is (you can just copy and paste them):

Title

Improve doc of FUNCTION_OR_LINK_NAMES

Content

This is PR for improving docs of functions/links. Related issue: #2182

Modified functions/links:
 - LIST HERE
 - ...

After merged

Congratulations! Check the task list below in this issue. Wait some time and check the latest version of the document! Functions: http://docs.chainer.org/en/latest/reference/functions.html Links: http://docs.chainer.org/en/latest/reference/links.html

Document for functions

Documentation contents will be:

Description: describe a function in natural language and mathematically, if possible
Input: describe input type and shape and other conditions
Output: describe output type and shape
See-also: if there should be reference for another functions/links
Example: write a runnable example code, good to understand it.

You can see also numpy documentations for reference.

Template

You can see the example of doc for sigmoid function here: https://github.com/pfnet/chainer/blob/master/chainer/functions/activation/sigmoid.py Template will be:

Element-wise sigmoid logistic function.

 .. math:: f(x)=(1 + \\exp(-x))^{-1}.

Args:
    x (:class:`~chainer.Variable` or :class:`numpy.ndarray` or \
    :class:`cupy.ndarray`):
        Input variable. A :math:`(s_1, s_2, ..., s_N)`-shaped float array.
    use_cudnn (bool): If ``True`` and cuDNN is enabled, then this function
        uses cuDNN as the core implementation.

Returns:
    ~chainer.Variable: Output variable. A
    :math:`(s_1, s_2, ..., s_N)`-shaped float array.

.. admonition:: Example

    >>> x = np.random.uniform(0, 1, (3, 4)).astype('f')
    >>> y = F.sigmoid(x)
    >>> y.shape
    (3, 4)

See also for the compiled doc: http://docs.chainer.org/en/latest/reference/functions.html#sigmoid

Adding example

We strongly recommend you to use interactive python (like ipython) to think good example of its function. What example should be the most understandable for users? Some documentations of numpy and other famous libraries might be helpful.

Figures (optional)

If you think figures might be much more helpful, please see http://matplotlib.org/sampledoc/extensions.html#inserting-matplotlib-plots . And below might be also helpful to think what the figures should look like.

• numpy.exp (the bottom plots)
• Transfer Function Layers (from torch.nn)

However, of course you CAN make PR without figures! Sometimes faster is better than perfect. And there is no criteria for whether figure is needed. It’s up to you!

List of functions

Activation

Source files: https://github.com/pfnet/chainer/tree/master/chainer/functions/activation

• clipped_relu #2208
• crelu #2229
• elu #2229
• hard_sigmoid #2398
• leaky_relu #2399
• log_softmax #2411
• lstm #2460
• maxout #2451
• prelu
• relu #2208 #2399
• sigmoid #1907 #2208 #2398
• slstm #2460
• softmax #2362 #2751
• softplus #2401
• tanh #2229

Array manipulation

Source files: https://github.com/pfnet/chainer/tree/master/chainer/functions/array

• broadcast #2229
• cast #2486
• concat #2229
• copy #2674
• depth2space #2675
• dstack #2664
• expand_dims #2677
• flatten #2678
• get_item #4375
• hstack #2491
• permutate #3407
• reshape #2678
• rollaxis
• select_item #3407
• separate #3407
• space2depth #2675
• split_axis
• squeeze #3307
• stack #2491
• swapaxes #3307
• tile #2825
• transpose #3302 #3307
• transpose_sequence #4719
• vstack #2491
• where #3301

Neural network connection

Source files: https://github.com/pfnet/chainer/tree/master/chainer/functions/connection

• bilinear
• convolution_2d #2490
• convolution_nd #2590
• deconvolution_2d #2616
• deconvolution_nd #2672
• dilated_convolution_2d
• embed_id #3091
• linear #2189 #2208
• n_step_lstm #3349

Evaluation

• accuracy #2633
• binary_accuracy #3102
• classification_summary
• r2_score

Loss

• black_out
• contrastive #3564
• crf1d
• cross_covariance
• ctc
• decov
• hinge #3108
• huber_loss #3563
• mean_absolute_error
• mean_squared_error
• negative_sampling
• sigmoid_cross_entropy #3562
• softmax_cross_entropy #3105
• triplet #3564
• vae

Math

• batch_l2_norm_squared
• bias
• ceil
• clip
• det
• exponential
• exponential_m1
• floor
• hyperbolic
• identity
• inv
• linear_interpolate
• logarithm_1p
• logsumexp
• matmul
• maximum
• minimum
• minmax
• scale
• sqrt
• square
• squared_difference
• sum #3497
• trigonometric

Noise

• dropout #3116
• gaussian

Pooling

• average_pooling_2d
• average_pooling_nd
• average_pooling_nd_kernel
• max_pooling_2d
• max_pooling_nd
• max_pooling_nd_kernel
• pooling_2d
• pooling_nd
• pooling_nd_kernel
• roi_pooling_2d
• spatial_pyramid_pooling_2d
• unpooling_2d
• upsampling_2d

Util

• forget

Document for links

Template

Templates? Anyone modifying the first link?

See also for the compiled doc:

List of links

Activation

• maxout
• prelu

Connection

• bias
• bilinear
• convolution_2d
• convolution_nd
• deconvolution_2d
• deconvolution_nd
• dilated_convolution_2d
• embed_id #3091
• gru #3858
• highway
• inception
• inceptionbn
• linear #3103
• lstm #3104
• mlp_convolution_2d
• n_step_lstm
• parameter
• peephole
• scale
• zoneoutlstm

Loss

• black_out
• crf1d
• hierarchical_softmax
• negative_sampling

Others

• dataset.convert.concat_examples

[keisuke-umezawa]

updated the issue checklists for #2411, #2460, #2491, #2590, #2616, #2633, #2664

[keisuke-umezawa]

updated the issue checklists for #2486 #2490, which have been already merged.