<!--
 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="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Documentation &mdash; NuttX latest documentation</title>
      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
      <link rel="stylesheet" href="../_static/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 src="../_static/jquery.js"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
        <script src="../_static/doctools.js"></script>
        <script src="../_static/sphinx_highlight.js"></script>
    <script 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
  

  </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>
    
    <option value="../../11.0.0" >11.0.0</option>
    
    <option value="../../12.0.0" >12.0.0</option>
    
    <option value="../../12.1.0" >12.1.0</option>
    
    <option value="../../12.2.0" >12.2.0</option>
    
    <option value="../../12.2.1" >12.2.1</option>
    
    <option value="../../12.3.0" >12.3.0</option>
    
    <option value="../../12.4.0" >12.4.0</option>
    
    <option value="../../12.5.0" >12.5.0</option>
    
    <option value="../../12.5.1" >12.5.1</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" aria-label="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="Navigation menu">
              <p class="caption" role="heading"><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="../quickstart/index.html">Getting Started</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="../platforms/index.html">Supported Platforms</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="../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 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><ul>
<li class="toctree-l4"><a class="reference internal" href="#live-rebuild">Live Rebuild</a></li>
</ul>
</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="Mobile navigation menu" >
          <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="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">Contributing</a></li>
      <li class="breadcrumb-item active">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">
             
  <section id="documentation">
<h1>Documentation<a class="headerlink" href="#documentation" title="Permalink to this heading"></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>
<section id="building">
<h2>Building<a class="headerlink" href="#building" title="Permalink to this heading"></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<span class="w"> </span>install<span class="w"> </span>pipenv
<span class="gp">$ </span>pipenv<span class="w"> </span>install
<span class="gp">$ </span><span class="c1"># activate the virtual environent</span>
<span class="gp">$ </span>pipenv<span class="w"> </span>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<span class="w"> </span>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<span class="w"> </span>_build/html/index.html
</pre></div>
</div>
</div></blockquote>
</div></blockquote>
<section id="live-rebuild">
<h3>Live Rebuild<a class="headerlink" href="#live-rebuild" title="Permalink to this heading"></a></h3>
<p>For more comfortable editing and previewing of changes (as <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> will perform a slower full rebuild),
you can install <code class="docutils literal notranslate"><span class="pre">sphinx-autobuild</span></code> which will monitor file changes and rebuild only affected files. To
install it (within the virtual environment):</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip3<span class="w"> </span>install<span class="w"> </span>sphinx-autobuild
</pre></div>
</div>
<p>To run:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>autobuild
</pre></div>
</div>
<p>Which will perform an initial clean build and monitor changes from then on.</p>
</section>
</section>
<section id="contributing">
<h2>Contributing<a class="headerlink" href="#contributing" title="Permalink to this heading"></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>
</section>
<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 heading"></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>
</section>
<section id="documentation-conventions">
<h2>Documentation Conventions<a class="headerlink" href="#documentation-conventions" title="Permalink to this heading"></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>
<section id="indentation">
<h3>Indentation<a class="headerlink" href="#indentation" title="Permalink to this heading"></a></h3>
<p>Child blocks should be indented two-spaces. This includes itemizations/enumerations.</p>
</section>
<section id="headings">
<h3>Headings<a class="headerlink" href="#headings" title="Permalink to this heading"></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>
</section>
<section id="code">
<h3>Code<a class="headerlink" href="#code" title="Permalink to this heading"></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>
</section>
<section id="linking">
<h3>Linking<a class="headerlink" href="#linking" title="Permalink to this heading"></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.
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>
<p>Linking to a specific document can be done with <code class="docutils literal notranslate"><span class="pre">:doc:`/path/to/document`</span></code> (without <code class="docutils literal notranslate"><span class="pre">.rst</span></code> extension).</p>
</section>
<section id="notes-and-todos">
<h3>Notes and TODOS<a class="headerlink" href="#notes-and-todos" title="Permalink to this heading"></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>
</section>
<section id="user-indications">
<h3>User Indications<a class="headerlink" href="#user-indications" title="Permalink to this heading"></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>
</section>
<section id="tabbed-examples">
<h3>Tabbed examples<a class="headerlink" href="#tabbed-examples" title="Permalink to this heading"></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>
</section>
</section>
<section id="tips">
<h2>Tips<a class="headerlink" href="#tips" title="Permalink to this heading"></a></h2>
<section id="spacing">
<h3>Spacing<a class="headerlink" href="#spacing" title="Permalink to this heading"></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>
</section>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="coding_style.html" class="btn btn-neutral float-left" title="C Coding Standard" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="../glossary.html" class="btn btn-neutral float-right" title="Glossary" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2020, The Apache Software Foundation.</p>
  </div>

   
</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>