Incubator-mxnet: API Doc Improvements - Tracking
Let's fix our docs!
The effort to spruce up MXNet's Python API docs is picking up steam but could use your help to add that extra oomph! Many of the APIs now have proper explanations and good examples, but we still have much more to go!
Here’s how you can join in and help:
Pick a few functions (or at least 1 :smile: ) from the list below
- Ensure you only pick ones that don’t have a current owner assigned and you can submit within 2 business days. Post a comment to the issue with the ones you’ve selected.
Look up current documentation
- Find whats currently documented for the function at the mxnet.io python API docs or within the C++ code in git.
Write up:
- A clear and concise description of the function and its behavior.
- List and describe each parameter with the valid input values, whether it is required or optional, and default value if the parameter is optional.
- Illustrate the function and parameter behavior using examples
- Refer to these examples for guidance:- Embedding , ROIPooling , Reshape
Submit your work
- Creating a new issue with [API docs submission] ‘your function name(s)’ in the title and paste your write-up markdown
OR - Creating a pull request for a change to the appropriate .cc or .py file. Instructions here: How to make a pull request for docs
- Creating a new issue with [API docs submission] ‘your function name(s)’ in the title and paste your write-up markdown
API List
| # | Function Name | Package | Contributor | Status |
|-----|--------------------------------------------------------------------|---------------|----------------------|------------------|
| 1 |
- - [ ] IRHeader
| 2 |
- - [ ] pack
| 3 |
- - [ ] pack_img
| 4 |
- - [ ] unpack
| 5 |
- - [ ] unpack_img
| 6 |
- - [ ] BilinearSampler
| 7 |
- - [ ] Correlation
| 8 |
- - [ ] GridGenerator
| 9 |
- - [ ] IdentityAttachKLSparseReg
| 10 |
- - [ ] SpatialTransformer
| 11 |
- - [ ] UpSampling
| 12 |
- - [ ] adam_update
| 13 |
- - [ ] ones_like
| 14 |
- - [ ] random_exponential
| 15 |
- - [ ] random_gamma
| 16 |
- - [ ] random_generalized_negative_binomial
| 17 |
- - [ ] random_negative_binomial
| 18 |
- - [ ] random_poisson
| 19 |
- - [x] rmsprop_update
| 20 |
- - [x] rmspropalex_update
| 21 |
- - [ ] sample_exponential
| 22 |
- - [ ] sample_gamma
| 23 |
- - [ ] sample_generalized_negative_binomial
| 24 |
- - [ ] sample_negative_binomial
| 25 |
- - [ ] sample_normal
| 26 |
- - [ ] sample_poisson
| 27 |
- - [ ] sample_uniform
| 28 |
- - [ ] sgd_mom_update
| 29 |
- - [ ] sgd_update
| 30 |
- - [ ] smooth_l1
| 31 |
- - [ ] softmax_cross_entropy
| 32 |
- - [ ] waitall
| 33 |
- - [ ] zeros_like
| 34 |
- - [ ] Caffe
| 35 |
- - [ ] Torch
| 36 |
- - [ ] check_label_shapes
| 37 |
- - [ ] Bilinear
| 38 |
- - [ ] FusedRNN
| 39 |
- - [ ] LSTMBias
| 40 |
- - [ ] LogValidationMetricsCallback
| 41 |
- - [ ] _init_torch_module
| 42 |
- - [ ] _make_torch_function
| 43 |
- - [ ] CustomOp.assign
| 44 |
- - [ ] NameManager
| 45 |
- - [ ] Monitor
| 46 |
- - [ ] CastAug
| 47 |
- - [ ] CenterCropAug
| 48 |
- - [ ] ColorJitterAug
| 49 |
- - [ ] ColorNormalizeAug
| 50 |
- - [ ] CreateAugmenter
| 51 |
- - [ ] HorizontalFlipAug
| 52 |
- - [ ] LightingAug
| 53 |
- - [ ] RandomCropAug
| 54 |
- - [ ] RandomOrderAug
| 55 |
- - [ ] RandomSizedCropAug
| 56 |
- - [ ] ResizeAug
| 57 |
- - [ ] center_crop
| 58 |
- - [ ] color_normalize
| 59 |
- - [ ] fixed_crop
| 60 |
- - [ ] imdecode
| 61 |
- - [ ] random_crop
| 62 |
- - [ ] random_size_crop
| 63 |
- - [ ] resize_short
| 64 |
- - [ ] scale_down
| 65 |
- - [ ] ImageIter.augmentation_transform
| 66 |
- - [ ] ImageIter.imdecode
| 67 |
- - [ ] ImageIter.postprocess_data
| 68 |
- - [ ] ImageIter.read_image
| 69 |
- - [ ] ImageIter.check_data_shape
| 70 |
- - [ ] ImageIter.check_valid_image
| 71 |
- - [ ] Executor._get_dict
| 72 |
- - [ ] _monitor_callback_wrapper
| 73 |
- - [ ] MultiBoxDetection
| 74 |
- - [ ] MultiBoxPrior
| 75 |
- - [ ] MultiBoxTarget
| 76 |
- - [ ] Proposal
| 77 |
- - [ ] count_sketch
| 78 |
- - [ ] fft
| 79 |
- - [ ] ifft
| 80 |
- - [ ] set_is_training
| 81 |
- - [ ] test
| 82 |
- - [ ] train
| 83 |
- - [ ] MXNetError
| 84 |
- - [ ] mx_float_p
| 85 |
- - [ ] py_str
| 86 |
- - [ ] print_summary
| 87 |
- - [ ] Symbol.attr
| 88 |
- - [ ] Symbol.attr_dict
| 89 |
- - [ ] Symbol.debug_str
| 90 |
- - [ ] Symbol.grad
| 91 |
- - [ ] Symbol.list_attr
| 92 |
- - [ ] MXRecordIO.close
| 93 |
- - [ ] MXRecordIO.open
| 94 |
- - [ ] Optimizer.set_lr_mult
| 95 |
- - [ ] Optimizer.set_lr_scale
| 96 |
- - [ ] Optimizer.set_wd_mult
| 97 |
- - [ ] Optimizer.update
| 98 |
- - [ ] LinearRegressionOutput
| 99 |
- - [x] NDArray._at
| 100 |
- - [x] NDArray._slice
| 101 |
- - [x] NDArray._sync_copyfrom
| 102 |
- - [ ] gamma
| 103 |
- - [ ] gammaln
| 104 |
- - [ ] identity
| 105 |
- - [ ] load
| 106 |
- - [ ] moveaxis
| 107 |
- - [ ] DataDesc
| 108 |
- - [ ] DataDesc.get_batch_axis
| 109 |
- - [ ] DataDesc.get_list
| 110 |
- - [ ] DataIter.getpad
| 111 |
- - [ ] MXDataIter
| 112 |
- - [ ] ImageDetRecordIter
| 113 |
- - [ ] Initializer._legacy_init
| 114 |
- - [ ] Initializer.dumps
| 115 |
- - [ ] ProgressBar
| 116 |
- - [ ] log_train_metric
| 117 |
- - [ ] module_checkpoint
| 118 |
- - [ ] _parse_aux_states
| 119 |
- - [ ] _parse_location
| 120 |
- - [x] check_symbolic_backward
| 121 |
- - [x] check_symbolic_forward
| 122 |
- - [ ] np_reduce
| 123 |
- - [ ] numeric_grad
| 124 |
- - [ ] print_max_err_loc
| 125 |
- - [ ] BucketSentenceIter
| 126 |
- - [ ] encode_sentences
| 127 |
- - [ ] do_rnn_checkpoint
| 128 |
- - [ ] load_rnn_checkpoint
| 129 |
- - [ ] save_rnn_checkpoint
| 130 |
- - [ ] BaseRNNCell.begin_state
| 131 |
- - [ ] BaseRNNCell.pack_weights
| 132 |
- - [ ] BaseRNNCell.unpack_weights
| 133 |
- - [ ] BaseRNNCell.unroll
| 134 |
- - [ ] BidirectionalCell
| 135 |
- - [ ] DropoutCell
| 136 |
- - [ ] FusedRNNCell
| 137 |
- - [ ] GRUCell
| 138 |
- - [ ] LSTMCell
| 139 |
- - [ ] ModifierCell
| 140 |
- - [ ] RNNCell
| 141 |
- - [ ] RNNParams
| 142 |
- - [ ] RNNParams.get
| 143 |
- - [ ] SequentialRNNCell
| 144 |
- - [ ] SequentialRNNCell.add
| 145 |
- - [ ] ZoneoutCell
| 146 |
- - [ ] BaseRNNCell._get_activation
| 147 |
- - [ ] FusedRNNCell._slice_weights
| 148 |
- - [ ] dump_profile
| 149 |
- - [ ] profiler_set_config
| 150 |
- - [ ] profiler_set_state
| 151 |
- - [ ] CustomOp
| 152 |
- - [ ] CustomOp.backward
| 153 |
- - [ ] CustomOp.forward
| 154 |
- - [ ] CustomOpProp
| 155 |
- - [ ] CustomOpProp.infer_shape
| 156 |
- - [ ] CustomOpProp.list_arguments
| 157 |
- - [ ] CustomOpProp.list_auxiliary_states
| 158 |
- - [ ] CustomOpProp.list_outputs
| 159 |
- - [x]
NDArrayOp.declare_backward_
| 160 |
- - [x]
NumpyOp
| 161 |
- - [x]
PythonOp
| 162 |
- - [x]
PythonOp.backward
| 163 |
- - [x]
PythonOp.forward
| 164 |
- - [x]
PythonOp.get_symbol
| 165 |
- - [x]
PythonOp.infer_shape
| 166 |
- - [x]
PythonOp.list_arguments
| 167 |
- - [x]
PythonOp.list_outputs
| 168 |
- - [x]
PythonOp.need_top_grad
| 169 |
- - [ ] register
| 170 |
- - [ ] CustomOpProp.infer_type
| 171 |
- - [ ] NameManager.get
| 172 |
- - [ ] Prefix
| 173 |
- - [ ] Monitor.install
| 174 |
- - [ ] Monitor.tic
| 175 |
- - [ ] Monitor.toc
| 176 |
- - [ ] Monitor.toc_print
| 177 |
- - [ ] getLogger
| 178 |
- - [x] KVStore.load_optimizer_states
| 179 |
- - [x] KVStore.save_optimizer_states
| 180 |
- - [x ] KVStore.set_optimizer
| 181 |
- - [x] create
| 182 |
- - [ ] ImageIter
| 183 |
- - [ ] ImageIter.next
| 184 |
- - [ ] ImageIter.next_sample
| 185 |
- - [ ] ImageIter.reset
| 186 |
- - [x] Executor
| 187 |
- - [x] Executor.backward
| 188 |
- - [x] Executor.copy_params_from
| 189 |
- - [x] Executor.reshape
| 190 |
- - [x] Executor.set_monitor_callback
| 191 |
- - [ ] Executor._get_outputs
| 192 |
- - [x] Executor.debug_str
| 193 |
- - [ ] compute_gradient
| 194 |
- - [ ] grad_and_loss
| 195 |
- - [ ] mark_variables
| 196 |
- - [ ] set_recording
| 197 |
- - [ ] LogMetricsCallback
| 198 |
- - [ ] TrainingStateScope
| 199 |
- - [ ] build_param_doc
| 200 |
- - [ ] c_array
| 201 |
- - [ ] c_str
| 202 |
- - [ ] check_call
| 203 |
- - [ ] ctypes2buffer
| 204 |
- - [ ] ctypes2numpy_shared
| 205 |
- - [ ] _load_lib
| 206 |
- - [ ] _notify_shutdown
| 207 |
- - [ ] add_fileline_to_docstring
| 208 |
- - [ ] AttrScope
| 209 |
- - [ ] AttrScope.current
| 210 |
- - [ ] AttrScope.get
domdivakaruni
All 28 comments
NumpyOP pythonop and ndarrayop are deprecated. We only support customop now
piiswrong
on 27 Apr 2017
I will document "LinearRegressionOutput" API
naidu0830
on 27 Apr 2017
I will document all samplers and randoms as I anyway enhanced or authored them, namely
random_gamma
random_exponential
random_poisson
random_negative_binomial
random_generalized_negative_binomial
sample_uniform
sample_normal
sample_gamma
sample_exponential
sample_poisson
sample_negative_binomial
sample_generalized_negative_binomial
I may need more than 2 business days but should be definitely done by end of next week.
asmushetzel
on 27 Apr 2017
I will document Functions from 125 to 147 in the rnn package.
If I get more time, I will also work on 161-168
moontails
on 27 Apr 2017
@moontails that is tremendous thank you! Do you plan on making PR's or creating Issues with your functions in markdown? When you are done with your first function send it in so we can help with a review before you get rolling with the rest. great stuff!
domdivakaruni
on 27 Apr 2017
@domdivakaruni I was thinking of creating PR's.
Thats a good idea! I will submit a PR when am done with the changes for the first function and gather all feedback before diving in on the rest :)
moontails
on 27 Apr 2017
I can document some of ndarray operators:
102 gamma ndarray
103 gammaln ndarray
104 identity ndarray
105 load ndarray
106 moveaxis ndarray
zhenwendai
on 27 Apr 2017
Hi @moontails do you want to call ownership of all 22 rnn functions at once or do you want to stake your claim in batches as you make progress?
domdivakaruni
on 28 Apr 2017
I will work on zeros_like, ones_like, softmax_cross_entropy, c_array, c_str
yuruofeifei
on 28 Apr 2017
I can work on resize_short, scale_down.
jhwei
on 28 Apr 2017
@yuruofeifei @jhwei @zhenwendai good stuff!
domdivakaruni
on 28 Apr 2017
@domdivakaruni either works fine for me. I had hoped to send out a PR yesterday to get some feedback before working on the rest, but ran into some issues setting up the repo (with the whole installing mxnet and make lint)
moontails
on 28 Apr 2017
@moontails did you get it worked out? Let me know what you ran into.
@nswamy fyi
domdivakaruni
on 28 Apr 2017
@moontails whats the issue that you are running into?
@domdivakaruni can we have folks picks few APIs at once and add more to their bucket as they make progress?
nswamy
on 28 Apr 2017
I can document 6~11.
Question : Should we use reST or Markdown for improvement through github issues? This page says Markdown, but pull request pages requires reST.
Lyken17
on 28 Apr 2017
@Lyken17 please prefer to use reST and submit a PR. If you want to just submit doc outside of the the code(python doc string or describe method of C++ code) use either reST or Markdown and submit an issue.
nswamy
on 28 Apr 2017
@zhenwendai, The docs for these APIs are already updated. Could you please pick a different set?
102 gamma ndarray
103 gammaln ndarray
104 identity ndarray
nswamy
on 29 Apr 2017
I will work on 58 color_normalize. BTW, where are the definitions of 78 fft & 79 ifft?
srviest
on 3 May 2017
I can document 2-5.
jiayue666
on 3 May 2017
I can share 130-145 with @moontails. Let me know which ones would you prefer that I do.
@piiswrong do we need to document 146 BaseRNNCell._get_activation and 147 FusedRNNCell._slice_weights? These are not intended for use other than by the APIs.
szha
on 3 May 2017
@moontails are you still working on these APIs? What can you share with @szha? can you please let us know as soon as you can? Thanks!
domdivakaruni
on 4 May 2017
@domdivakaruni @szha I am sorry guys, I still havent been able to get it to work on my Macbook.
I will let @szha start checking things off from 130-145 and get back on track if I am able to unblock myself.
moontails
on 4 May 2017
@moontails Don't know which problem you ran into but also had to resolve some hiccups on my mac. Resolved it by:
- Complete fresh clone of the whole mxnet
- Not running all build/installs for this repo. Just the documentation creation as described in the doc referenced in section 4. at the beginning of this thread.
- In file tests/ci_build/install/ubuntu_install_python.sh bypassed the certificate checking by
wget https://bootstrap.pypa.io/get-pip.py --no-check-certificate
That got me going. I used a separate mxnet repo for standard building/installation and functional testing (I had to touch a bit more than just the "describe" section of the operators). Don't know whether this was necessary, but at least it worked that way.
Did punt on lint on my mac as I couldn't get it to work. Rather did submit the pull request and fixed the flagged lint issues based on the automatic tests. It's straightforward.
asmushetzel
on 4 May 2017
I'm going to take the four APIs for kvstore 178 - 181
eric-haibin-lin
on 4 May 2017
@Lyken17 any luck updating the doc for the APIs that you picked ?
nswamy
on 5 May 2017
Hi @nswamy
I just updated GridGenerator and submit it to issue https://github.com/dmlc/mxnet/issues/6147.
I meet troubles when documenting ndarray.UpSampling. Even myself cannot find the proper way to use it, according to issues https://github.com/dmlc/mxnet/issues/2823 https://github.com/dmlc/mxnet/issues/4134 https://github.com/dmlc/mxnet/issues/1412, it seems to be an incomplete implementation. I also looked up several FCN mxnet implementations, they all use deconvolution instead of UpSampling.
Lyken17
on 8 May 2017
@Lyken17, Thanks for posting the issue, I will convert this to actual documentation in code.
You can skip UpSampling for now, we might need to add a note that it is incomplete. @mli, @piiswrong what do you suggest?
For other APIs that you work on, can you please edit the docs in the code directly? If building and rendering takes time or you get into an issue, you can skip that step and just follow the tips to avoid any lint errors.
nswamy
on 9 May 2017
Hi @nswamy
I've just posted a pr for 118 and 119: https://github.com/dmlc/mxnet/pull/6314
One thing though is that I wasn't able to get rendering going on my Mac. "make lint" was fine, but building docs was always failing. I'll post a separate issue perhaps to get some advice on that.
apaleyes
on 18 May 2017
Related issues
yuconglin
·
3Comments
xzqjack
·
3Comments
luoruisichuan
·
3Comments
sbodenstein
·
3Comments
GuilongZh
·
3Comments
Most helpful comment
I will document all samplers and randoms as I anyway enhanced or authored them, namely
random_gamma
random_exponential
random_poisson
random_negative_binomial
random_generalized_negative_binomial
sample_uniform
sample_normal
sample_gamma
sample_exponential
sample_poisson
sample_negative_binomial
sample_generalized_negative_binomial
I may need more than 2 business days but should be definitely done by end of next week.