Deploying to gh-pages from @ 3f94bbf 🚀

_sources/developer/documentation.rst.txt

@@ -1,7 +1,7 @@
 .. _dev-documenting:
 
-Documentation - user manual and source code docs
-================================================
+Documentation
+=============
 
 AMR-Wind comes with two different types of documentation:
 
@@ -11,26 +11,27 @@ AMR-Wind comes with two different types of documentation:
 - Inline documentation within C++ source code that are written in a format that can be
   processed automatically by `Doxygen <http://www.doxygen.nl/manual/index.html>`_
 
-User documentation
-------------------
+Manual
+------
 
-AMR-Wind user documentation is written using a special format called
-ReStructured Text (ReST) and is converted into HTML and PDF formats using a
-python package Sphinx. Since the manuals are written in simple text files, they
-can be version controlled alongside the source code. Documentation is
-automatically generated with new updates to the GitHub repository and deployed
-at `AMR-Wind documentation site <https://exawind.github.io/amr-wind>`_.
+The AMR-Wind manual is written using a special format called
+ReStructured Text (ReST) and is converted into HTML and PDF formats
+using a python package Sphinx. Since the manuals are written in simple
+text files, they can be version controlled alongside the source
+code. Documentation is automatically generated with new updates to the
+GitHub repository and deployed at `AMR-Wind documentation site
+<https://exawind.github.io/amr-wind>`_.
 
-Writing user documentation
-``````````````````````````
+Writing documentation
+`````````````````````
 
 As mentioned previously, documentation is written using a special text format
 called reStructuredText. Sphinx user manual provides a `reST Primer
 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ that
 provides an overview of this format and how to write documentation using this format.
 
 
-Documenting source code
+Source code documentation
 -------------------------
 
 Source code (C++ files) are commented using a special format that
@@ -52,14 +53,45 @@ to rely on comments to follow the code structure.
 Building documentation
 ----------------------
 
-To generate this documentation on a local machine, or to rebuild docs
-during code development, `doxygen`, `graphviz`, `doxysphinx`, and
-`sphinx` are required, as well as turning on the
-`AMR_WIND_ENABLE_DOCUMENTATION` cmake option.
-```{shell}
-$ cd build && cmake -DAMR_WIND_ENABLE_DOCUMENTATION:BOOL=ON .. && cmake --build . -t docs
-```
-The resulting documentation is in `docs/spinx/html` directory.Documentation can
-also be generated in other formats, consult `Sphinx docs
-<https://www.sphinx-doc.org/en/master/usage/builders/index.html>`_ for available
-formats and their usage.
+Dependencies
+````````````
+
+To generate the AMR-Wind manual on a local machine, `doxygen`,
+`graphviz`, `doxysphinx`, `enchant`, and `sphinx` are required.
+
+To install the required packages on Linux:
+
+.. code-block:: console
+
+    $ sudo apt-get install -y --no-install-recommends graphviz libenchant-2-dev
+
+and on OSX with homebrew:
+
+.. code-block:: console
+
+    $ brew install doxygen graphviz enchant
+
+To install the required python packages:
+
+.. code-block:: console
+
+    $ pip install sphinx sphinx_rtd_theme sphinx_toolbox sphinx_copybutton pyenchant sphinxcontrib-spelling doxysphinx
+
+Build
+`````
+
+Run the following command to build the documentation:
+
+.. code-block:: console
+
+    $ cd build && cmake -DAMR_WIND_ENABLE_DOCUMENTATION:BOOL=ON .. && cmake --build . -t docs
+
+.. tip::
+
+   On OSX, before running the cmake, you may need to :code:`$ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib`
+
+The resulting documentation is in `docs/spinx/html`
+directory. Documentation can also be generated in other formats,
+consult `Sphinx docs
+<https://www.sphinx-doc.org/en/master/usage/builders/index.html>`_ for
+available formats and their usage.

developer/coding_guidelines.html

@@ -8,7 +8,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Coding Guidelines &mdash; AMR-Wind 0.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
-      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=7ab3649f" />
+      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
       <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
 
 
@@ -49,7 +49,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../user/user.html">User Manual</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../theory/theory.html">Theory Manual</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer Documentation</a><ul class="current">
-<li class="toctree-l2"><a class="reference internal" href="documentation.html">Documentation - user manual and source code docs</a></li>
+<li class="toctree-l2"><a class="reference internal" href="documentation.html">Documentation</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../doxygen/html/index.html">AMR-Wind API</a></li>
 <li class="toctree-l2"><a class="reference internal" href="unit_testing.html">Unit testing</a></li>
 <li class="toctree-l2"><a class="reference internal" href="regression_testing.html">Regression testing</a></li>

developer/documentation.html

@@ -6,9 +6,9 @@
   <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Documentation - user manual and source code docs &mdash; AMR-Wind 0.1 documentation</title>
+  <title>Documentation &mdash; AMR-Wind 0.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
-      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=7ab3649f" />
+      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
       <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
 
 
@@ -50,13 +50,17 @@
 <li class="toctree-l1"><a class="reference internal" href="../user/user.html">User Manual</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../theory/theory.html">Theory Manual</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer Documentation</a><ul class="current">
-<li class="toctree-l2 current"><a class="current reference internal" href="#">Documentation - user manual and source code docs</a><ul>
-<li class="toctree-l3"><a class="reference internal" href="#user-documentation">User documentation</a><ul>
-<li class="toctree-l4"><a class="reference internal" href="#writing-user-documentation">Writing user documentation</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="#manual">Manual</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="#writing-documentation">Writing documentation</a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="#source-code-documentation">Source code documentation</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#building-documentation">Building documentation</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="#dependencies">Dependencies</a></li>
+<li class="toctree-l4"><a class="reference internal" href="#build">Build</a></li>
 </ul>
 </li>
-<li class="toctree-l3"><a class="reference internal" href="#documenting-source-code">Documenting source code</a></li>
-<li class="toctree-l3"><a class="reference internal" href="#building-documentation">Building documentation</a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="../doxygen/html/index.html">AMR-Wind API</a></li>
@@ -83,7 +87,7 @@
   <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">Developer Documentation</a></li>
-      <li class="breadcrumb-item active">Documentation - user manual and source code docs</li>
+      <li class="breadcrumb-item active">Documentation</li>
       <li class="wy-breadcrumbs-aside">
             <a href="../_sources/developer/documentation.rst.txt" rel="nofollow"> View page source</a>
       </li>
@@ -93,32 +97,32 @@
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">
 
-  <section id="documentation-user-manual-and-source-code-docs">
-<span id="dev-documenting"></span><h1>Documentation - user manual and source code docs<a class="headerlink" href="#documentation-user-manual-and-source-code-docs" title="Link to this heading"></a></h1>
+  <section id="documentation">
+<span id="dev-documenting"></span><h1>Documentation<a class="headerlink" href="#documentation" title="Link to this heading"></a></h1>
 <p>AMR-Wind comes with two different types of documentation:</p>
 <ul class="simple">
 <li><p>The manual, i.e., the document you are reading now, that is
 written using <a class="reference external" href="https://www.sphinx-doc.org/en/master/index.html">Sphinx</a>, and</p></li>
 <li><p>Inline documentation within C++ source code that are written in a format that can be
 processed automatically by <a class="reference external" href="http://www.doxygen.nl/manual/index.html">Doxygen</a></p></li>
 </ul>
-<section id="user-documentation">
-<h2>User documentation<a class="headerlink" href="#user-documentation" title="Link to this heading"></a></h2>
-<p>AMR-Wind user documentation is written using a special format called
-ReStructured Text (ReST) and is converted into HTML and PDF formats using a
-python package Sphinx. Since the manuals are written in simple text files, they
-can be version controlled alongside the source code. Documentation is
-automatically generated with new updates to the GitHub repository and deployed
-at <a class="reference external" href="https://exawind.github.io/amr-wind">AMR-Wind documentation site</a>.</p>
-<section id="writing-user-documentation">
-<h3>Writing user documentation<a class="headerlink" href="#writing-user-documentation" title="Link to this heading"></a></h3>
+<section id="manual">
+<h2>Manual<a class="headerlink" href="#manual" title="Link to this heading"></a></h2>
+<p>The AMR-Wind manual is written using a special format called
+ReStructured Text (ReST) and is converted into HTML and PDF formats
+using a python package Sphinx. Since the manuals are written in simple
+text files, they can be version controlled alongside the source
+code. Documentation is automatically generated with new updates to the
+GitHub repository and deployed at <a class="reference external" href="https://exawind.github.io/amr-wind">AMR-Wind documentation site</a>.</p>
+<section id="writing-documentation">
+<h3>Writing documentation<a class="headerlink" href="#writing-documentation" title="Link to this heading"></a></h3>
 <p>As mentioned previously, documentation is written using a special text format
 called reStructuredText. Sphinx user manual provides a <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html">reST Primer</a> that
 provides an overview of this format and how to write documentation using this format.</p>
 </section>
 </section>
-<section id="documenting-source-code">
-<h2>Documenting source code<a class="headerlink" href="#documenting-source-code" title="Link to this heading"></a></h2>
+<section id="source-code-documentation">
+<h2>Source code documentation<a class="headerlink" href="#source-code-documentation" title="Link to this heading"></a></h2>
 <p>Source code (C++ files) are commented using a special format that
 allows Doxygen to extract the annotated comments and create source
 code documentation as well as inheritance diagrams. The
@@ -135,16 +139,38 @@ <h2>Documenting source code<a class="headerlink" href="#documenting-source-code"
 </section>
 <section id="building-documentation">
 <h2>Building documentation<a class="headerlink" href="#building-documentation" title="Link to this heading"></a></h2>
-<p>To generate this documentation on a local machine, or to rebuild docs
-during code development, <cite>doxygen</cite>, <cite>graphviz</cite>, <cite>doxysphinx</cite>, and
-<cite>sphinx</cite> are required, as well as turning on the
-<cite>AMR_WIND_ENABLE_DOCUMENTATION</cite> cmake option.
-<code class="docutils literal notranslate"><span class="pre">`{shell}</span>
-<span class="pre">$</span> <span class="pre">cd</span> <span class="pre">build</span> <span class="pre">&amp;&amp;</span> <span class="pre">cmake</span> <span class="pre">-DAMR_WIND_ENABLE_DOCUMENTATION:BOOL=ON</span> <span class="pre">..</span> <span class="pre">&amp;&amp;</span> <span class="pre">cmake</span> <span class="pre">--build</span> <span class="pre">.</span> <span class="pre">-t</span> <span class="pre">docs</span>
-<span class="pre">`</span></code>
-The resulting documentation is in <cite>docs/spinx/html</cite> directory.Documentation can
-also be generated in other formats, consult <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/builders/index.html">Sphinx docs</a> for available
-formats and their usage.</p>
+<section id="dependencies">
+<h3>Dependencies<a class="headerlink" href="#dependencies" title="Link to this heading"></a></h3>
+<p>To generate the AMR-Wind manual on a local machine, <cite>doxygen</cite>,
+<cite>graphviz</cite>, <cite>doxysphinx</cite>, <cite>enchant</cite>, and <cite>sphinx</cite> are required.</p>
+<p>To install the required packages on Linux:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>--no-install-recommends<span class="w"> </span>graphviz<span class="w"> </span>libenchant-2-dev
+</pre></div>
+</div>
+<p>and on OSX with homebrew:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>brew<span class="w"> </span>install<span class="w"> </span>doxygen<span class="w"> </span>graphviz<span class="w"> </span>enchant
+</pre></div>
+</div>
+<p>To install the required python packages:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>sphinx<span class="w"> </span>sphinx_rtd_theme<span class="w"> </span>sphinx_toolbox<span class="w"> </span>sphinx_copybutton<span class="w"> </span>pyenchant<span class="w"> </span>sphinxcontrib-spelling<span class="w"> </span>doxysphinx
+</pre></div>
+</div>
+</section>
+<section id="build">
+<h3>Build<a class="headerlink" href="#build" title="Link to this heading"></a></h3>
+<p>Run the following command to build the documentation:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">cd</span><span class="w"> </span>build<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>cmake<span class="w"> </span>-DAMR_WIND_ENABLE_DOCUMENTATION:BOOL<span class="o">=</span>ON<span class="w"> </span>..<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>cmake<span class="w"> </span>--build<span class="w"> </span>.<span class="w"> </span>-t<span class="w"> </span>docs
+</pre></div>
+</div>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>On OSX, before running the cmake, you may need to <code class="code docutils literal notranslate"><span class="pre">$</span> <span class="pre">export</span> <span class="pre">PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib</span></code></p>
+</div>
+<p>The resulting documentation is in <cite>docs/spinx/html</cite>
+directory. Documentation can also be generated in other formats,
+consult <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/builders/index.html">Sphinx docs</a> for
+available formats and their usage.</p>
+</section>
 </section>
 </section>