Google Git
Sign in
apache / singa-site / be983bc44db8673b80f36c133d1ceb12926645fd / . / content / develop / contribute-docs.html
blob: 21127e195a82171e0eacb9ecdea8eeb529c223ae [file] [log] [blame]
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>How to Contribute to Documentation &mdash; singa 2.0.0 documentation</title>
<script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'2.0.0',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="How to prepare a release" href="how-to-release.html" />
<link rel="prev" title="How to Contribute Code" href="contribute-code.html" />
<link href="../_static/style.css" rel="stylesheet" type="text/css">
<!--link href="../_static/fontawesome-all.min.css" rel="stylesheet" type="text/css"-->
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.0.13/css/all.css"
integrity="sha384-DNOHZ68U8hZfKXOrtjWvjxusGo9WQnrNx2sqG0tfsghAvtVlRW3tvkXWZh58N9jp" crossorigin="anonymous">
<style>
.fa:hover {
opacity: 0.7;
}
.fab:hover {
opacity: 0.7;
}
</style>
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> singa
<img src="../_static/singa.png" class="logo" alt="Logo"/>
</a>
<div class="version">
latest
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../docs/index.html">Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../downloads.html">Download SINGA</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security.html">Security</a></li>
</ul>
<p class="caption"><span class="caption-text">Development</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="contribute-code.html">How to Contribute Code</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">How to Contribute to Documentation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#website">Website</a></li>
<li class="toctree-l2"><a class="reference internal" href="#python-api">Python API</a></li>
<li class="toctree-l2"><a class="reference internal" href="#cpp-api">CPP API</a></li>
<li class="toctree-l2"><a class="reference internal" href="#using-visual-studio-code-vscode">Using Visual Studio Code (vscode)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#preview">Preview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#docstring-snippet">Docstring Snippet</a></li>
<li class="toctree-l3"><a class="reference internal" href="#spell-check">Spell Check</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="how-to-release.html">How to prepare a release</a></li>
</ul>
<p class="caption"><span class="caption-text">Community</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../community/source-repository.html">Source Repository</a></li>
<li class="toctree-l1"><a class="reference internal" href="../community/mail-lists.html">Project Mailing Lists</a></li>
<li class="toctree-l1"><a class="reference internal" href="../community/issue-tracking.html">Issue Tracking</a></li>
<li class="toctree-l1"><a class="reference internal" href="../community/team-list.html">The SINGA Team</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">singa</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> &raquo;</li>
<li>How to Contribute to Documentation</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<!--
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.
--><div class="section" id="how-to-contribute-to-documentation">
<h1>How to Contribute to Documentation<a class="headerlink" href="#how-to-contribute-to-documentation" title="Permalink to this headline"></a></h1>
<div class="section" id="website">
<h2>Website<a class="headerlink" href="#website" title="Permalink to this headline"></a></h2>
<p>This document gives step-by-step instructions for deploying <a class="reference external" href="http://singa.apache.org">SINGA website</a>.</p>
<p>SINGA website is built by <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> from a source tree stored in the <a class="reference external" href="https://github.com/apache/singa/tree/master/doc">git repo</a>.</p>
<p>To install Sphinx:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">U</span> <span class="n">Sphinx</span><span class="o">==</span><span class="mf">1.5</span><span class="o">.</span><span class="mi">6</span>
</pre></div>
</div>
<p>To install the markdown support for Sphinx:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">recommonmark</span><span class="o">==</span><span class="mf">0.5</span><span class="o">.</span><span class="mi">0</span>
</pre></div>
</div>
<p>To install the rtd theme:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">sphinx_rtd_theme</span><span class="o">==</span><span class="mf">0.4</span><span class="o">.</span><span class="mi">3</span>
</pre></div>
</div>
<p>You can build the website by executing the following command from the doc folder:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">build</span><span class="o">.</span><span class="n">sh</span> <span class="n">html</span>
</pre></div>
</div>
<p>Committers can update the <a class="reference external" href="http://singa.apache.org/en/index.html">SINGA website</a> by copying the updated files to the <a class="reference external" href="https://github.com/apache/singa-site">website repo</a> (suppose the site repo is ~/singa-sit)</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">_build</span>
<span class="n">rsync</span> <span class="o">--</span><span class="n">checksum</span> <span class="o">-</span><span class="n">rvh</span> <span class="n">html</span><span class="o">/</span> <span class="o">~/</span><span class="n">singa</span><span class="o">-</span><span class="n">site</span><span class="o">/</span>
<span class="n">cd</span> <span class="o">~/</span><span class="n">singa</span><span class="o">-</span><span class="n">site</span>
<span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;update xxxx&quot;</span>
<span class="n">git</span> <span class="n">push</span>
</pre></div>
</div>
<p>We fix the versions of the libs in order to generate the same (checksum) html file if the source file is not changed. Otherwise, everytime we build the documentation, the html file of the same source file could be different. As a result, many html files in the site repo need updating.</p>
</div>
<div class="section" id="python-api">
<h2>Python API<a class="headerlink" href="#python-api" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="cpp-api">
<h2>CPP API<a class="headerlink" href="#cpp-api" title="Permalink to this headline"></a></h2>
<p>To generate docs, run &#8220;doxygen&#8220; from the doc folder (Doxygen &gt;= 1.8 recommended)</p>
</div>
<div class="section" id="using-visual-studio-code-vscode">
<h2>Using Visual Studio Code (vscode)<a class="headerlink" href="#using-visual-studio-code-vscode" title="Permalink to this headline"></a></h2>
<div class="section" id="preview">
<h3>Preview<a class="headerlink" href="#preview" title="Permalink to this headline"></a></h3>
<p>The document files (rst and md files) can be previewed in vscode via the <a class="reference external" href="https://docs.restructuredtext.net/">reStructuredText Extension</a>.</p>
<ol>
<li><p class="first">Install the extension in vscode.</p>
</li>
<li><p class="first">Install the dependent libs. All libs required to build the website should be installed (see the above instructions). In addition, there are two more libs to be installed.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span> <span class="n">pip</span> <span class="n">install</span> <span class="n">sphinx</span><span class="o">-</span><span class="n">autobuild</span><span class="o">=</span><span class="mf">0.7</span><span class="o">.</span><span class="mi">1</span>
<span class="n">pip</span> <span class="n">install</span> <span class="n">doc8</span><span class="o">=</span><span class="mf">0.8</span><span class="o">.</span><span class="mi">0</span>
</pre></div>
</div>
</li>
<li><p class="first">Configure the conf path for <code class="docutils literal"><span class="pre">restructuredtext.confPath</span></code> to the <a class="reference external" href="./conf.py">conf.py</a></p>
</li>
</ol>
</div>
<div class="section" id="docstring-snippet">
<h3>Docstring Snippet<a class="headerlink" href="#docstring-snippet" title="Permalink to this headline"></a></h3>
<p><a class="reference external" href="https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring">autoDocstring</a> generates the docstring of functions, classes, etc. Choose the DocString Format to <code class="docutils literal"><span class="pre">google</span></code>.</p>
</div>
<div class="section" id="spell-check">
<h3>Spell Check<a class="headerlink" href="#spell-check" title="Permalink to this headline"></a></h3>
<p><a class="reference external" href="https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker">Code Spell Checker</a> can be configured to check the comments of the code, or .md and .rst files.</p>
<p>To do spell check only for comments of Python code, add the following snippet via <code class="docutils literal"><span class="pre">File</span> <span class="pre">-</span> <span class="pre">Preferences</span> <span class="pre">-</span> <span class="pre">User</span> <span class="pre">Snippets</span> <span class="pre">-</span> <span class="pre">python.json</span></code></p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;cspell check&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s2">&quot;prefix&quot;</span><span class="p">:</span> <span class="s2">&quot;cspell&quot;</span><span class="p">,</span>
<span class="s2">&quot;body&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;# Directives for doing spell check only for python and c/cpp comments&quot;</span><span class="p">,</span>
<span class="s2">&quot;# cSpell:includeRegExp #.* &quot;</span><span class="p">,</span>
<span class="s2">&quot;# cSpell:includeRegExp (</span><span class="se">\&quot;\&quot;\&quot;</span><span class="s2">|&#39;&#39;&#39;)[^</span><span class="se">\1</span><span class="s2">]*</span><span class="se">\1</span><span class="s2">&quot;</span><span class="p">,</span>
<span class="s2">&quot;# cSpell: CStyleComment&quot;</span><span class="p">,</span>
<span class="p">],</span>
<span class="s2">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;# spell check only for python comments&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>To do spell check only for comments of Cpp code, add the following snippet via <code class="docutils literal"><span class="pre">File</span> <span class="pre">-</span> <span class="pre">Preferences</span> <span class="pre">-</span> <span class="pre">User</span> <span class="pre">Snippets</span> <span class="pre">-</span> <span class="pre">cpp.json</span></code></p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;cspell check&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s2">&quot;prefix&quot;</span><span class="p">:</span> <span class="s2">&quot;cspell&quot;</span><span class="p">,</span>
<span class="s2">&quot;body&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;// Directive for doing spell check only for cpp comments&quot;</span><span class="p">,</span>
<span class="s2">&quot;// cSpell:includeRegExp CStyleComment&quot;</span><span class="p">,</span>
<span class="p">],</span>
<span class="s2">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;# spell check only for cpp comments&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="how-to-release.html" class="btn btn-neutral float-right" title="How to prepare a release" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="contribute-code.html" class="btn btn-neutral float-left" title="How to Contribute Code" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2019 The Apache Software Foundation. All rights reserved. Apache SINGA, Apache, the Apache feather logo, and the Apache SINGA project logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> singa </span>
v: latest
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>Languages</dt>
<dd><a href=".././index.html">English</a></dd>
<dd><a href=".././zh/index.html">中文</a></dd>
</dl>
<dl>
<dt>Versions</dt>
<dd><a href="http://singa.apache.org/v0.3.0/">0.3</a></dd>
<dd><a href="http://singa.apache.org/v1.1.0/">1.1</a></dd>
</dl>
</div>
<a href="http://www.apache.org"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">Foundation</a>
<a href="http://www.apache.org/events/current-event"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">Events</a>
<a href="http://www.apache.org/foundation/thanks.html"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">Thanks</a>
<a href="http://www.apache.org/foundation/sponsorship.html"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">Sponsorship</a>
<a href="http://www.apache.org/licenses/"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">License</a>
<br>
<a href="https://github.com/apache/singa" class="fa fa-github"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://aws.amazon.com/marketplace/seller-profile?id=5bcac385-12c4-4802-aec7-351e09b77b4c"
class="fab fa-aws"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://hub.docker.com/r/apache/singa/" class="fab fa-docker"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://www.linkedin.com/groups/13550034" class="fa fa-linkedin"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://twitter.com/ApacheSinga" class="fa fa-twitter"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://www.facebook.com/Apache-SINGA-347284219056544/" class="fa fa-facebook"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://www.researchgate.net/project/Apache-SINGA" class="fab fa-researchgate"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
</div>
<a href="https://github.com/apache/singa">
<img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub">
</a>
</body>
</html>