versions/master/community/document.html

<!---
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you 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.
-->
---
layout: default
---
<script>

</script>
<article class="post">

    <header class="post-header wrapper">
        <h1 class="post-title">Write Document and Tutorials</h1>
        <h3>Guidelines on documentation to help the community.</h3><a style="float:left; margin-top:20px" href="/versions/master/community/index" class="btn btn-action">Contribute
            <span class="span-accented">›</span></a></header>

    <div class="post-content">
        <div class="wrapper">
            <!--- Licensed to the Apache Software Foundation (ASF) under one -->
<!--- or more contributor license agreements.  See the NOTICE file -->
<!--- distributed with this work for additional information -->
<!--- regarding copyright ownership.  The ASF licenses this file -->
<!--- to you 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. -->

<h1 id="write-document-and-tutorials">Write Document and Tutorials</h1>

<p>We use the <a href="http://sphinx-doc.org">Sphinx</a> for the main documentation.
Sphinx support both the reStructuredText and markdown. When possible, we
encourage to use reStructuredText as it has richer features. Note that
the python doc-string and tutorials allow you to embed reStructuredText
syntax.</p>

<h2 id="document-python">Document Python</h2>

<p>We use <a href="https://numpydoc.readthedocs.io/en/latest/">numpydoc</a> format to
document the function and classes. The following snippet gives an
example docstring. We always document all the public functions, when
necessary, provide an usage example of the features we support(as shown
below).</p>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">myfunction</span><span class="p">(</span><span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">,</span> <span class="n">arg3</span><span class="o">=</span><span class="mi">3</span><span class="p">):</span>
    <span class="s">"""Briefly describe my function.

    Parameters
    ----------
    arg1 : Type1
        Description of arg1

    arg2 : Type2
        Description of arg2

    arg3 : Type3, optional
        Description of arg3

    Returns
    -------
    rv1 : RType1
        Description of return type one

    Examples
    --------
    .. code:: python

        # Example usage of myfunction
        x = myfunction(1, 2)
    """</span>
    <span class="k">return</span> <span class="n">rv1</span>
</code></pre></div></div>

<p>Be careful to leave blank lines between sections of your documents. In
the above case, there has to be a blank line before
[Parameters]{.title-ref}, [Returns]{.title-ref} and
[Examples]{.title-ref} in order for the doc to be built correctly. To
add a new function to the doc, we need to add the
<a href="http://www.sphinx-doc.org/en/master/ext/autodoc.html">sphinx.autodoc</a>
rules to the
<a href="https://github.com/apache/incubator-mxnet/tree/master/docs/python_docs/python">/docs/python_docs/python</a>).
You can refer to the existing files under this folder on how to add the
functions.</p>

<h2 id="document-c">Document C++</h2>

<p>We use the doxgen format to document c++ functions. The following
snippet shows an example of c++ docstring.</p>

<div class="language-cpp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/*!
 * \brief Description of my function
 * \param arg1 Description of arg1
 * \param arg2 Description of arg2
 * \returns describe return value
 */</span>
<span class="kt">int</span> <span class="nf">myfunction</span><span class="p">(</span><span class="kt">int</span> <span class="n">arg1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">arg2</span><span class="p">)</span> <span class="p">{</span>
  <span class="c1">// When necessary, also add comment to clarify internal logic</span>
<span class="p">}</span>
</code></pre></div></div>

<p>Besides documenting function usages, we also highly recommend
contributors to add comments about code logic to improve readability.</p>

<h2 id="write-tutorials">Write Tutorials</h2>

<p>We use the <a href="https://github.com/aaren/notedown">notedown</a> to write Jupyter notebooks
in Markdown as Python tutorials. You can find the source code under
<a href="https://github.com/apache/incubator-mxnet/tree/master/docs/python_docs/python/tutorials">/docs/python_docs/python/tutorials</a>.</p>

<p>The tutorial code will run on our build server to generate the document
page and the tutorial page will show the result of executing the Jupyter notebook.</p>

<h2 id="application-examples">Application Examples</h2>

<p>Our deep learning examples are maintained in <a href="http://github.com/apache/incubator-mxnet-examples">apache/incubator-mxnet-examples</a>
and are checked regularly by CI to ensure quality.</p>

<script async="" defer="" src="https://buttons.github.io/buttons.js"></script>

<script src="https://apis.google.com/js/platform.js"></script>


        </div>
    </div>

</article>