versions/master/community/document.html - mxnet-site - Git at Google

 <!DOCTYPE html>
 <html lang=" en"><head>
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <link href="https://raw.githubusercontent.com/dmlc/web-data/master/mxnet/image/mxnet-icon.png" rel="icon" type="image/png"><!-- Begin Jekyll SEO tag v2.6.1 -->
 <title>Write Document and Tutorials | Apache MXNet</title>
 <meta name="generator" content="Jekyll v4.0.0" />
 <meta property="og:title" content="Write Document and Tutorials" />
 <meta property="og:locale" content="en_US" />
 <meta name="description" content="A flexible and efficient library for deep learning." />
 <meta property="og:description" content="A flexible and efficient library for deep learning." />
 <link rel="canonical" href="https://mxnet.apache.org/versions/master/community/document" />
 <meta property="og:url" content="https://mxnet.apache.org/versions/master/community/document" />
 <meta property="og:site_name" content="Apache MXNet" />
 <script type="application/ld+json">
 {"url":"https://mxnet.apache.org/versions/master/community/document","headline":"Write Document and Tutorials","description":"A flexible and efficient library for deep learning.","@type":"WebPage","@context":"https://schema.org"}</script>
 <!-- End Jekyll SEO tag -->
 <script src="https://medium-widget.pixelpoint.io/widget.js"></script>
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
   <link rel="stylesheet" href="/versions/master/assets/main.css"><link type="application/atom+xml" rel="alternate" href="https://mxnet.apache.org/versions/master/feed.xml" title="Apache MXNet" /><script>
 if(!(window.doNotTrack === "1" || navigator.doNotTrack === "1" || navigator.doNotTrack === "yes" || navigator.msDoNotTrack === "1")) {
   (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
   (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
   m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
   })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

   ga('create', 'UA-96378503-1', 'auto');
   ga('send', 'pageview');
 }
 </script>

 <script src="/versions/master/assets/js/jquery-3.3.1.min.js"></script><script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js" defer></script>
   <script src="/versions/master/assets/js/globalSearch.js" defer></script>
   <script src="/versions/master/assets/js/clipboard.js" defer></script>
   <script src="/versions/master/assets/js/copycode.js" defer></script></head>
 <body><header class="site-header" role="banner">

   <script>
     $(document).ready(function () {

       // HEADER OPACITY LOGIC

       function opacity_header() {
         var value = "rgba(4,140,204," + ($(window).scrollTop() / 300 + 0.4) + ")"
         $('.site-header').css("background-color", value)
       }

       $(window).scroll(function () {
         opacity_header()
       })
       opacity_header();

       // MENU SELECTOR LOGIC
       $('.page-link').each( function () {
         if (window.location.href.includes(this.href)) {
           $(this).addClass("page-current");
         }
       });
     })
   </script>
   <div class="wrapper">
     <a class="site-title" rel="author" href="/versions/master/"><img
             src="/versions/master/assets/img/mxnet_logo.png" class="site-header-logo"></a>
     <nav class="site-nav">
       <input type="checkbox" id="nav-trigger" class="nav-trigger"/>
       <label for="nav-trigger">
           <span class="menu-icon">
             <svg viewBox="0 0 18 15" width="18px" height="15px">
               <path d="M18,1.484c0,0.82-0.665,1.484-1.484,1.484H1.484C0.665,2.969,0,2.304,0,1.484l0,0C0,0.665,0.665,0,1.484,0 h15.032C17.335,0,18,0.665,18,1.484L18,1.484z M18,7.516C18,8.335,17.335,9,16.516,9H1.484C0.665,9,0,8.335,0,7.516l0,0 c0-0.82,0.665-1.484,1.484-1.484h15.032C17.335,6.031,18,6.696,18,7.516L18,7.516z M18,13.516C18,14.335,17.335,15,16.516,15H1.484 C0.665,15,0,14.335,0,13.516l0,0c0-0.82,0.665-1.483,1.484-1.483h15.032C17.335,12.031,18,12.695,18,13.516L18,13.516z"/>
             </svg>
           </span>
       </label>
       <div class="gs-search-border">
         <div id="gs-search-icon"></div>
         <form id="global-search-form">
           <input id="global-search" type="text" title="Search" placeholder="Search" />
           <div id="global-search-dropdown-container">
             <button class="gs-current-version btn" type="button" data-toggle="dropdown">
                 <span id="gs-current-version-label">master</span>
                 <svg class="gs-dropdown-caret" viewBox="0 0 32 32" class="icon icon-caret-bottom" aria-hidden="true">
                     <path class="dropdown-caret-path" d="M24 11.305l-7.997 11.39L8 11.305z"></path>
                 </svg>
             </button>
             <ul class="gs-opt-group gs-version-dropdown">


                   <li class="gs-opt gs-versions active">master</li>


                   <li class="gs-opt gs-versions">1.7.0</li>


                   <li class="gs-opt gs-versions">1.6.0</li>


                   <li class="gs-opt gs-versions">1.5.0</li>


                   <li class="gs-opt gs-versions">1.4.1</li>


                   <li class="gs-opt gs-versions">1.3.1</li>


                   <li class="gs-opt gs-versions">1.2.1</li>


                   <li class="gs-opt gs-versions">1.1.0</li>


                   <li class="gs-opt gs-versions">1.0.0</li>


                   <li class="gs-opt gs-versions">0.12.1</li>


                   <li class="gs-opt gs-versions">0.11.0</li>


             </ul>
         </div>
           <span id="global-search-close">x</span>
         </form>
       </div>
       <div class="trigger">
         <div id="global-search-mobile-border">
           <div id="gs-search-icon-mobile"></div>
           <input id="global-search-mobile" placeholder="Search..." type="text"/>
           <div id="global-search-dropdown-container-mobile">
             <button class="gs-current-version-mobile btn" type="button" data-toggle="dropdown">
                 <svg class="gs-dropdown-caret" viewBox="0 0 32 32" class="icon icon-caret-bottom" aria-hidden="true">
                     <path class="dropdown-caret-path" d="M24 11.305l-7.997 11.39L8 11.305z"></path>
                 </svg>
             </button>
             <ul class="gs-opt-group gs-version-dropdown-mobile">


                   <li class="gs-opt gs-versions active">master</li>


                   <li class="gs-opt gs-versions">1.7.0</li>


                   <li class="gs-opt gs-versions">1.6.0</li>


                   <li class="gs-opt gs-versions">1.5.0</li>


                   <li class="gs-opt gs-versions">1.4.1</li>


                   <li class="gs-opt gs-versions">1.3.1</li>


                   <li class="gs-opt gs-versions">1.2.1</li>


                   <li class="gs-opt gs-versions">1.1.0</li>


                   <li class="gs-opt gs-versions">1.0.0</li>


                   <li class="gs-opt gs-versions">0.12.1</li>


                   <li class="gs-opt gs-versions">0.11.0</li>


             </ul>
         </div>
         </div>
         <a class="page-link" href="/versions/master/get_started">Get Started</a>
         <a class="page-link" href="/versions/master/blog">Blog</a>
         <a class="page-link" href="/versions/master/features">Features</a>
         <a class="page-link" href="/versions/master/ecosystem">Ecosystem</a>
         <a class="page-link" href="/versions/master/api">Docs & Tutorials</a>
         <a class="page-link" href="https://github.com/apache/incubator-mxnet">GitHub</a>
         <div class="dropdown">
           <span class="dropdown-header">master
             <svg class="dropdown-caret" viewBox="0 0 32 32" class="icon icon-caret-bottom" aria-hidden="true"><path class="dropdown-caret-path" d="M24 11.305l-7.997 11.39L8 11.305z"></path></svg>
           </span>
           <div class="dropdown-content">


                 <a class="dropdown-option-active" href="/">master</a>


                 <a href="/versions/1.7.0/">1.7.0</a>


                 <a href="/versions/1.6.0/">1.6.0</a>


                 <a href="/versions/1.5.0/">1.5.0</a>


                 <a href="/versions/1.4.1/">1.4.1</a>


                 <a href="/versions/1.3.1/">1.3.1</a>


                 <a href="/versions/1.2.1/">1.2.1</a>


                 <a href="/versions/1.1.0/">1.1.0</a>


                 <a href="/versions/1.0.0/">1.0.0</a>


                 <a href="/versions/0.12.1/">0.12.1</a>


                 <a href="/versions/0.11.0/">0.11.0</a>


           </div>
         </div>
       </div>
     </nav>
   </div>
 </header>
 <main class="page-content" aria-label="Content">
     <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 Descroption 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 logics</span>
 <span class="p">}</span>
 </code></pre></div></div>

 <p>Besides documenting function usages, we also highly recommend
 contributors to add comments about code logics 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>

 </main><footer class="site-footer h-card">
     <div class="wrapper">
         <div class="row">
             <div class="col-4">
                 <h4 class="footer-category-title">Resources</h4>
                 <ul class="contact-list">
                     <li><a href="/versions/master/community#stay-connected">Mailing lists</a></li>
                     <li><a href="https://discuss.mxnet.io">MXNet Discuss forum</a></li>
                     <li><a href="/versions/master/community#github-issues">Github Issues</a></li>
                     <li><a href="https://github.com/apache/incubator-mxnet/projects">Projects</a></li>
                     <li><a href="https://cwiki.apache.org/confluence/display/MXNET/Apache+MXNet+Home">Developer Wiki</a></li>
                     <li><a href="/versions/master/community">Contribute To MXNet</a></li>

                 </ul>
             </div>

             <div class="col-4"><ul class="social-media-list"><li><a href="https://github.com/apache/incubator-mxnet"><svg class="svg-icon"><use xlink:href="/versions/master/assets/minima-social-icons.svg#github"></use></svg> <span class="username">apache/incubator-mxnet</span></a></li><li><a href="https://www.twitter.com/apachemxnet"><svg class="svg-icon"><use xlink:href="/versions/master/assets/minima-social-icons.svg#twitter"></use></svg> <span class="username">apachemxnet</span></a></li><li><a href="https://youtube.com/apachemxnet"><svg class="svg-icon"><use xlink:href="/versions/master/assets/minima-social-icons.svg#youtube"></use></svg> <span class="username">apachemxnet</span></a></li></ul>
 </div>

             <div class="col-4 footer-text">
                 <p>A flexible and efficient library for deep learning.</p>
             </div>
         </div>
     </div>
 </footer>
 <footer class="site-footer2">
     <div class="wrapper">
         <div class="row">
             <div class="col-3">
                 <img src="/versions/master/assets/img/apache_incubator_logo.png" class="footer-logo col-2">
             </div>
             <div class="footer-bottom-warning col-9">
                 <p>Apache MXNet is an effort undergoing incubation at The Apache Software Foundation (ASF), <span
                         style="font-weight:bold">sponsored by the <i>Apache Incubator</i></span>. Incubation is required
                     of all newly accepted projects until a further review indicates that the infrastructure,
                     communications, and decision making process have stabilized in a manner consistent with other
                     successful ASF projects. While incubation status is not necessarily a reflection of the completeness
                     or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
                 </p><p>"Copyright © 2017-2018, The Apache Software Foundation Apache MXNet, MXNet, Apache, the Apache
                     feather, and the Apache MXNet project logo are either registered trademarks or trademarks of the
                     Apache Software Foundation."</p>
             </div>
         </div>
     </div>
 </footer>


 </body>

 </html>
	<!DOCTYPE html>
	<html lang=" en"><head>
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<link href="https://raw.githubusercontent.com/dmlc/web-data/master/mxnet/image/mxnet-icon.png" rel="icon" type="image/png"><!-- Begin Jekyll SEO tag v2.6.1 -->
	<title>Write Document and Tutorials \| Apache MXNet</title>
	<meta name="generator" content="Jekyll v4.0.0" />
	<meta property="og:title" content="Write Document and Tutorials" />
	<meta property="og:locale" content="en_US" />
	<meta name="description" content="A flexible and efficient library for deep learning." />
	<meta property="og:description" content="A flexible and efficient library for deep learning." />
	<link rel="canonical" href="https://mxnet.apache.org/versions/master/community/document" />
	<meta property="og:url" content="https://mxnet.apache.org/versions/master/community/document" />
	<meta property="og:site_name" content="Apache MXNet" />
	<script type="application/ld+json">
	{"url":"https://mxnet.apache.org/versions/master/community/document","headline":"Write Document and Tutorials","description":"A flexible and efficient library for deep learning.","@type":"WebPage","@context":"https://schema.org"}</script>
	<!-- End Jekyll SEO tag -->
	<script src="https://medium-widget.pixelpoint.io/widget.js"></script>
	<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
	<link rel="stylesheet" href="/versions/master/assets/main.css"><link type="application/atom+xml" rel="alternate" href="https://mxnet.apache.org/versions/master/feed.xml" title="Apache MXNet" /><script>
	if(!(window.doNotTrack === "1" \|\| navigator.doNotTrack === "1" \|\| navigator.doNotTrack === "yes" \|\| navigator.msDoNotTrack === "1")) {
	(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]\|\|function(){
	(i[r].q=i[r].q\|\|[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
	m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
	})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

	ga('create', 'UA-96378503-1', 'auto');
	ga('send', 'pageview');
	}
	</script>

	<script src="/versions/master/assets/js/jquery-3.3.1.min.js"></script><script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js" defer></script>
	<script src="/versions/master/assets/js/globalSearch.js" defer></script>
	<script src="/versions/master/assets/js/clipboard.js" defer></script>
	<script src="/versions/master/assets/js/copycode.js" defer></script></head>
	<body><header class="site-header" role="banner">

	<script>
	$(document).ready(function () {

	// HEADER OPACITY LOGIC

	function opacity_header() {
	var value = "rgba(4,140,204," + ($(window).scrollTop() / 300 + 0.4) + ")"
	$('.site-header').css("background-color", value)
	}

	$(window).scroll(function () {
	opacity_header()
	})
	opacity_header();

	// MENU SELECTOR LOGIC
	$('.page-link').each( function () {
	if (window.location.href.includes(this.href)) {
	$(this).addClass("page-current");
	}
	});
	})
	</script>
	<div class="wrapper">
	<a class="site-title" rel="author" href="/versions/master/"><img
	src="/versions/master/assets/img/mxnet_logo.png" class="site-header-logo"></a>
	<nav class="site-nav">
	<input type="checkbox" id="nav-trigger" class="nav-trigger"/>
	<label for="nav-trigger">
	<span class="menu-icon">
	<svg viewBox="0 0 18 15" width="18px" height="15px">
	<path d="M18,1.484c0,0.82-0.665,1.484-1.484,1.484H1.484C0.665,2.969,0,2.304,0,1.484l0,0C0,0.665,0.665,0,1.484,0 h15.032C17.335,0,18,0.665,18,1.484L18,1.484z M18,7.516C18,8.335,17.335,9,16.516,9H1.484C0.665,9,0,8.335,0,7.516l0,0 c0-0.82,0.665-1.484,1.484-1.484h15.032C17.335,6.031,18,6.696,18,7.516L18,7.516z M18,13.516C18,14.335,17.335,15,16.516,15H1.484 C0.665,15,0,14.335,0,13.516l0,0c0-0.82,0.665-1.483,1.484-1.483h15.032C17.335,12.031,18,12.695,18,13.516L18,13.516z"/>
	</svg>
	</span>
	</label>
	<div class="gs-search-border">
	<div id="gs-search-icon"></div>
	<form id="global-search-form">
	<input id="global-search" type="text" title="Search" placeholder="Search" />
	<div id="global-search-dropdown-container">
	<button class="gs-current-version btn" type="button" data-toggle="dropdown">
	<span id="gs-current-version-label">master</span>
	<svg class="gs-dropdown-caret" viewBox="0 0 32 32" class="icon icon-caret-bottom" aria-hidden="true">
	<path class="dropdown-caret-path" d="M24 11.305l-7.997 11.39L8 11.305z"></path>
	</svg>
	</button>
	<ul class="gs-opt-group gs-version-dropdown">


	<li class="gs-opt gs-versions active">master</li>



	<li class="gs-opt gs-versions">1.7.0</li>



	<li class="gs-opt gs-versions">1.6.0</li>



	<li class="gs-opt gs-versions">1.5.0</li>



	<li class="gs-opt gs-versions">1.4.1</li>



	<li class="gs-opt gs-versions">1.3.1</li>



	<li class="gs-opt gs-versions">1.2.1</li>



	<li class="gs-opt gs-versions">1.1.0</li>



	<li class="gs-opt gs-versions">1.0.0</li>



	<li class="gs-opt gs-versions">0.12.1</li>



	<li class="gs-opt gs-versions">0.11.0</li>


	</ul>
	</div>
	<span id="global-search-close">x</span>
	</form>
	</div>
	<div class="trigger">
	<div id="global-search-mobile-border">
	<div id="gs-search-icon-mobile"></div>
	<input id="global-search-mobile" placeholder="Search..." type="text"/>
	<div id="global-search-dropdown-container-mobile">
	<button class="gs-current-version-mobile btn" type="button" data-toggle="dropdown">
	<svg class="gs-dropdown-caret" viewBox="0 0 32 32" class="icon icon-caret-bottom" aria-hidden="true">
	<path class="dropdown-caret-path" d="M24 11.305l-7.997 11.39L8 11.305z"></path>
	</svg>
	</button>
	<ul class="gs-opt-group gs-version-dropdown-mobile">


	<li class="gs-opt gs-versions active">master</li>



	<li class="gs-opt gs-versions">1.7.0</li>



	<li class="gs-opt gs-versions">1.6.0</li>



	<li class="gs-opt gs-versions">1.5.0</li>



	<li class="gs-opt gs-versions">1.4.1</li>



	<li class="gs-opt gs-versions">1.3.1</li>



	<li class="gs-opt gs-versions">1.2.1</li>



	<li class="gs-opt gs-versions">1.1.0</li>



	<li class="gs-opt gs-versions">1.0.0</li>



	<li class="gs-opt gs-versions">0.12.1</li>



	<li class="gs-opt gs-versions">0.11.0</li>


	</ul>
	</div>
	</div>
	<a class="page-link" href="/versions/master/get_started">Get Started</a>
	<a class="page-link" href="/versions/master/blog">Blog</a>
	<a class="page-link" href="/versions/master/features">Features</a>
	<a class="page-link" href="/versions/master/ecosystem">Ecosystem</a>
	<a class="page-link" href="/versions/master/api">Docs & Tutorials</a>
	<a class="page-link" href="https://github.com/apache/incubator-mxnet">GitHub</a>
	<div class="dropdown">
	<span class="dropdown-header">master
	<svg class="dropdown-caret" viewBox="0 0 32 32" class="icon icon-caret-bottom" aria-hidden="true"><path class="dropdown-caret-path" d="M24 11.305l-7.997 11.39L8 11.305z"></path></svg>
	</span>
	<div class="dropdown-content">


	<a class="dropdown-option-active" href="/">master</a>



	<a href="/versions/1.7.0/">1.7.0</a>



	<a href="/versions/1.6.0/">1.6.0</a>



	<a href="/versions/1.5.0/">1.5.0</a>



	<a href="/versions/1.4.1/">1.4.1</a>



	<a href="/versions/1.3.1/">1.3.1</a>



	<a href="/versions/1.2.1/">1.2.1</a>



	<a href="/versions/1.1.0/">1.1.0</a>



	<a href="/versions/1.0.0/">1.0.0</a>



	<a href="/versions/0.12.1/">0.12.1</a>



	<a href="/versions/0.11.0/">0.11.0</a>


	</div>
	</div>
	</div>
	</nav>
	</div>
	</header>
	<main class="page-content" aria-label="Content">
	<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 Descroption 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 logics</span>
	<span class="p">}</span>
	</code></pre></div></div>

	<p>Besides documenting function usages, we also highly recommend
	contributors to add comments about code logics 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>

	</main><footer class="site-footer h-card">
	<div class="wrapper">
	<div class="row">
	<div class="col-4">
	<h4 class="footer-category-title">Resources</h4>
	<ul class="contact-list">
	<li><a href="/versions/master/community#stay-connected">Mailing lists</a></li>
	<li><a href="https://discuss.mxnet.io">MXNet Discuss forum</a></li>
	<li><a href="/versions/master/community#github-issues">Github Issues</a></li>
	<li><a href="https://github.com/apache/incubator-mxnet/projects">Projects</a></li>
	<li><a href="https://cwiki.apache.org/confluence/display/MXNET/Apache+MXNet+Home">Developer Wiki</a></li>
	<li><a href="/versions/master/community">Contribute To MXNet</a></li>

	</ul>
	</div>

	<div class="col-4"><ul class="social-media-list"><li><a href="https://github.com/apache/incubator-mxnet"><svg class="svg-icon"><use xlink:href="/versions/master/assets/minima-social-icons.svg#github"></use></svg> <span class="username">apache/incubator-mxnet</span></a></li><li><a href="https://www.twitter.com/apachemxnet"><svg class="svg-icon"><use xlink:href="/versions/master/assets/minima-social-icons.svg#twitter"></use></svg> <span class="username">apachemxnet</span></a></li><li><a href="https://youtube.com/apachemxnet"><svg class="svg-icon"><use xlink:href="/versions/master/assets/minima-social-icons.svg#youtube"></use></svg> <span class="username">apachemxnet</span></a></li></ul>
	</div>

	<div class="col-4 footer-text">
	<p>A flexible and efficient library for deep learning.</p>
	</div>
	</div>
	</div>
	</footer>
	<footer class="site-footer2">
	<div class="wrapper">
	<div class="row">
	<div class="col-3">
	<img src="/versions/master/assets/img/apache_incubator_logo.png" class="footer-logo col-2">
	</div>
	<div class="footer-bottom-warning col-9">
	<p>Apache MXNet is an effort undergoing incubation at The Apache Software Foundation (ASF), <span
	style="font-weight:bold">sponsored by the <i>Apache Incubator</i></span>. Incubation is required
	of all newly accepted projects until a further review indicates that the infrastructure,
	communications, and decision making process have stabilized in a manner consistent with other
	successful ASF projects. While incubation status is not necessarily a reflection of the completeness
	or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
	</p><p>"Copyright © 2017-2018, The Apache Software Foundation Apache MXNet, MXNet, Apache, the Apache
	feather, and the Apache MXNet project logo are either registered trademarks or trademarks of the
	Apache Software Foundation."</p>
	</div>
	</div>
	</div>
	</footer>




	</body>

	</html>