blob: d784eb20fa6ce6b362e9d908e86933aa6289193e [file] [log] [blame]
<!--
Documentation/_templates/layout.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.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Documentation &mdash; NuttX latest documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/segment.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/menu.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/tabs.css" type="text/css" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Glossary" href="../glossary.html" />
<link rel="prev" title="C Coding Standard" href="coding_style.html" />
</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"> NuttX
<img src="../_static/NuttX.png" class="logo" alt="Logo"/>
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select onchange="javascript:location.href = this.value;">
<option value="../../latest" selected="selected">latest</option>
<option value="../../10.0.0" >10.0.0</option>
<option value="../../10.0.1" >10.0.1</option>
<option value="../../10.1.0" >10.1.0</option>
<option value="../../10.2.0" >10.2.0</option>
<option value="../../10.3.0" >10.3.0</option>
</select>
</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">
<p class="caption"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../components/index.html">OS Components</a></li>
<li class="toctree-l1"><a class="reference internal" href="../applications/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../boards/index.html">Supported Boards</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Releases</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Contributing</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="workflow.html">Development Workflow</a></li>
<li class="toctree-l2"><a class="reference internal" href="making-changes.html">Making Changes Using Git</a></li>
<li class="toctree-l2"><a class="reference internal" href="coding_style.html">C Coding Standard</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Documentation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#building">Building</a></li>
<li class="toctree-l3"><a class="reference internal" href="#contributing">Contributing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#writing-restructure-text-with-sphinx">Writing ReStructure Text with Sphinx</a></li>
<li class="toctree-l3"><a class="reference internal" href="#documentation-conventions">Documentation Conventions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#indentation">Indentation</a></li>
<li class="toctree-l4"><a class="reference internal" href="#headings">Headings</a></li>
<li class="toctree-l4"><a class="reference internal" href="#code">Code</a></li>
<li class="toctree-l4"><a class="reference internal" href="#linking">Linking</a></li>
<li class="toctree-l4"><a class="reference internal" href="#notes-and-todos">Notes and TODOS</a></li>
<li class="toctree-l4"><a class="reference internal" href="#user-indications">User Indications</a></li>
<li class="toctree-l4"><a class="reference internal" href="#tabbed-examples">Tabbed examples</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#tips">Tips</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#spacing">Spacing</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</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">NuttX</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" class="icon icon-home"></a> &raquo;</li>
<li><a href="index.html">Contributing</a> &raquo;</li>
<li>Documentation</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/contributing/documentation.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="documentation">
<h1>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline"></a></h1>
<p>The Apache NuttX Documentation is built using the
<a class="reference external" href="https://www.sphinx-doc.org/en/master/">Sphinx documentation system</a>. Documentation
is written in <a class="reference external" href="https://docutils.sourceforge.io/rst.html">ReStructured Text</a> (RST),
with Sphinx-specific directives. RST is the format used for
<a class="reference external" href="https://docs.python.org/3/">Python documentation</a> and is also used in many other projects.
Using Sphinx, the RST files are rendered into HTML files that can be read in your browser.</p>
<div class="section" id="building">
<h2>Building<a class="headerlink" href="#building" title="Permalink to this headline"></a></h2>
<p>To render the Documentation locally, you should clone the NuttX main repository, and
go into <code class="docutils literal notranslate"><span class="pre">Documentation</span></code> directory. Then,</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>Install Sphinx and other dependencies using pipenv.
You may also find it helpful on platforms such as Windows and MacOS to use <em>pyenv</em>
to manage your python installation. You can read about installing that on the
project <a class="reference external" href="https://github.com/pyenv/pyenv#installation">site</a>.</p></li>
</ol>
<blockquote>
<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> pip3 install pipenv
<span class="gp">$</span> pipenv install
<span class="gp">$</span> <span class="c1"># activate the virtual environent</span>
<span class="gp">$</span> pipenv shell
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="2">
<li><p>Build documentation:</p></li>
</ol>
<blockquote>
<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> make html
</pre></div>
</div>
<p>The resulting HTMLs will end up under <code class="docutils literal notranslate"><span class="pre">_build/html</span></code>. You can open your browser at the root with:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> xdg-open _build/html/index.html
</pre></div>
</div>
</div></blockquote>
</div></blockquote>
</div>
<div class="section" id="contributing">
<h2>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline"></a></h2>
<p>Contributions to documentation are appreciated. These can be as simple as fixing a typo or formatting issues to more involved
changes such as documenting parts of NuttX which are not yet covered or even writing guides for other users.</p>
<p>The contribution workflow is the same as for the code, so check the <a class="reference internal" href="workflow.html"><span class="doc">Development Workflow</span></a> to understand
how your changes should be upstreamed.</p>
</div>
<div class="section" id="writing-restructure-text-with-sphinx">
<h2>Writing ReStructure Text with Sphinx<a class="headerlink" href="#writing-restructure-text-with-sphinx" title="Permalink to this headline"></a></h2>
<p>The following links can be used to learn about RST syntax and about Sphinx specific directives. Note that
sometimes Sphinx’s approach is used over standard RST since it is more powerful (e.g. standard linking vs Sphinx
<code class="docutils literal notranslate"><span class="pre">:ref:</span></code> which can be used across files, <code class="docutils literal notranslate"><span class="pre">code-block</span></code> directive vs <code class="docutils literal notranslate"><span class="pre">::</span></code> which allows specifying highlight language, etc.):</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/">Sphinx documentation system</a></p></li>
<li><p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">ReStructured Text documentation</a></p></li>
<li><p><a class="reference external" href="http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">Sphinx Guide to ReStructured Text</a></p></li>
<li><p><a class="reference external" href="https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html">Restructured Text cheat sheet</a></p></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="documentation-conventions">
<h2>Documentation Conventions<a class="headerlink" href="#documentation-conventions" title="Permalink to this headline"></a></h2>
<p>While RST/Sphinx provide many ways to do things, it is best to follow a given convention to mantain consistency and avoid
pitfalls. For this reason, documentation changes should follow the following set of conventions.</p>
<div class="section" id="indentation">
<h3>Indentation<a class="headerlink" href="#indentation" title="Permalink to this headline"></a></h3>
<p>Child blocks should be indented two-spaces. This includes itemizations/enumerations.</p>
</div>
<div class="section" id="headings">
<h3>Headings<a class="headerlink" href="#headings" title="Permalink to this headline"></a></h3>
<p>Three levels of headings should be used in general. The style used to mark sections is based around <code class="docutils literal notranslate"><span class="pre">=</span></code> and <code class="docutils literal notranslate"><span class="pre">-</span></code>.
Sections should look like this:</p>
<div class="highlight-RST notranslate"><div class="highlight"><pre><span></span><span class="gh">=================</span>
<span class="gh">Top Level Heading</span>
<span class="gh">=================</span>
<span class="gh">Subsection</span>
<span class="gh">==========</span>
<span class="gh">Subsubsection</span>
<span class="gh">-------------</span>
</pre></div>
</div>
</div>
<div class="section" id="code">
<h3>Code<a class="headerlink" href="#code" title="Permalink to this headline"></a></h3>
<p>Code should be documented using the <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain">C domain</a>.
This means for example that a function should be documented as:</p>
<div class="highlight-RST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">c:function</span><span class="p">::</span> bool myfunction(int arg1, int arg2)
Here the function should be described
<span class="nc">:param arg1:</span> Description of arg1
<span class="nc">:param arg2:</span> Description of arg2
<span class="nc">:return:</span> Description of return value
</pre></div>
</div>
<p>To document a piece of code, use a <code class="docutils literal notranslate"><span class="pre">code-block</span></code> <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block">directive</a>, specifying the highlight language. If the block is not of code but some verbatim piece of text,
it is acceptable to use RST standard <cite>::</cite>. This is specially useful and compact when used in the following mode:</p>
<div class="highlight-RST notranslate"><div class="highlight"><pre><span></span>The text file should have the following content<span class="se">::</span>
<span class="s"> Line1</span>
<span class="s"> Line2</span>
<span class="s"> Line3</span>
</pre></div>
</div>
</div>
<div class="section" id="linking">
<h3>Linking<a class="headerlink" href="#linking" title="Permalink to this headline"></a></h3>
<p>To generate internal links, Sphinx’s <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role">roles</a> should
be used. So, use <code class="docutils literal notranslate"><span class="pre">:ref:</span></code> instead of standard RST syntax like <code class="docutils literal notranslate"><span class="pre">`link</span> <span class="pre">&lt;target&gt;`_</span></code> for internal links.</p>
<p>Moreover, sphinx is configured to use <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#confval-autosectionlabel_prefix_document">autosectionlabel</a> extension. This means that sections will automatically get a label that can be linked with the
<cite>:ref:</cite>. For example:</p>
<div class="highlight-RST notranslate"><div class="highlight"><pre><span></span><span class="gh">This is a Section</span>
<span class="gh">=================</span>
<span class="na">:ref:</span><span class="nv">`This is a Section`</span> is a link to this very same section.
</pre></div>
</div>
<p>If the target is in a different file, you can refer it with: <code class="docutils literal notranslate"><span class="pre">:ref:`link</span> <span class="pre">text</span> <span class="pre">&lt;/pathtorst:Section</span> <span class="pre">Name&gt;`</span></code>.</p>
</div>
<div class="section" id="notes-and-todos">
<h3>Notes and TODOS<a class="headerlink" href="#notes-and-todos" title="Permalink to this headline"></a></h3>
<p>Use RST <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions">admonitions</a> to highlight things from the text,
such as a note that should be prominently displayed.</p>
<p>In case you need to leave a TODO note in the documentation to point that something needs to be improved, use a <code class="docutils literal notranslate"><span class="pre">todo</span></code> admonition,
which is available via the <code class="docutils literal notranslate"><span class="pre">sphinx.ext.todo</span></code> extension. This will let the reader of the documentation also know that the documentation
is not yet finished somewhere and may further motivate a contribution.</p>
</div>
<div class="section" id="user-indications">
<h3>User Indications<a class="headerlink" href="#user-indications" title="Permalink to this headline"></a></h3>
<p>To indicate a keypress, menu action or GUI button selection, use the following:</p>
<div class="highlight-RST notranslate"><div class="highlight"><pre><span></span>Go into menu <span class="na">:menuselection:</span><span class="nv">`File --&gt; Save As`</span>, click <span class="na">:guilabel:</span><span class="nv">`&amp;OK`</span> or press <span class="na">:kbd:</span><span class="nv">`Enter`</span>.
</pre></div>
</div>
<p>which would render as:</p>
<p>Go into menu <span class="menuselection">File ‣ Save As</span>, click <span class="guilabel"><span class="accelerator">O</span>K</span> or press <kbd class="kbd docutils literal notranslate">Enter</kbd>.</p>
</div>
<div class="section" id="tabbed-examples">
<h3>Tabbed examples<a class="headerlink" href="#tabbed-examples" title="Permalink to this headline"></a></h3>
<p>To indicate different instructions/examples for different scenarios (for example, different Operating
Systems) use the <a class="reference external" href="https://github.com/executablebooks/sphinx-tabs">tabs</a> extension (see link for examples).</p>
</div>
</div>
<div class="section" id="tips">
<h2>Tips<a class="headerlink" href="#tips" title="Permalink to this headline"></a></h2>
<div class="section" id="spacing">
<h3>Spacing<a class="headerlink" href="#spacing" title="Permalink to this headline"></a></h3>
<p>If you are getting formatting errors, be sure to provide the appropiate spacing between a directive and its content.
Generally, you should follow this format:</p>
<div class="highlight-RST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">directive</span><span class="p">::</span>
child content
non-child content which appears after previous directive
</pre></div>
</div>
<p>Note the line between directive and content and the indentation.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2020, The Apache Software Foundation
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>