Improving the code documentation

README.md

@@ -7,7 +7,7 @@
 
 <img src="docs/text/figs/animationspe11a.gif" width="830" height="360">
 
-This repository contains scripts to set up a workflow in python for the three cases in the SPE11 project.
+This repository contains scripts to set up a workflow in python for the three cases in the [_SPE11 project_](https://www.spe.org/en/csp/).
 Here we use the [_OPM-Flow_](https://opm-project.org/?page_id=19) simulator.
 
 ## Installation

dev-requirements.txt

@@ -1,4 +1,5 @@
 black
+numpydoc
 mypy
 pylint
 pytest-cov

docs/_sources/introduction.rst.txt

@@ -5,20 +5,21 @@ Introduction
 .. image:: ./figs/animationspe11a.gif
 
 This documentation describes the content of the **pyopmspe11** package.
-The numerical studies are performed using the `Flow <https://opm-project.org/?page_id=19>`_ simulator. 
+The numerical studies are performed using the `OPM Flow simulator <https://opm-project.org/?page_id=19>`_. 
 
 Concept
 -------
-Simplified and flexible framework for the three cases in the SPE Comparative Solution Project
+Simplified and flexible framework for the three cases in the `SPE Comparative Solution Project <https://www.spe.org/en/csp/>`_
 via a :doc:`configuration file <./configuration_file>`:
 
 - Set the path to the OPM Flow simulator and simulator flags.
-- Set the grid type (cartesian, tensor, or corner-point grid) and the number of cells.
+- Set the grid type (Cartesian, tensor, or corner-point grid) and the number of cells.
 - Set the rock and fluid properties.
-- Set the well or sources locations and injection schedule.
-- After execution. generates the data in the same format as requested in the benchmark.
-- In addition, generates .png figures for quick inspection.
-- Also, generates figures for comparison between runs (i.e., to assess sensitivities).  
+- Set the wells or sources locations and define the injection schedule.
+- Select the functionality (e.g., generate only the input decks, run the whole framework).
+- The framework generates the data in the same format as requested in the benchmark.
+- In addition, it generates .png figures for quick inspection of the results.
+- Also, it generates figures for comparison between runs (i.e., to assess sensitivities).  
 
 Overview
 --------

docs/introduction.html

@@ -89,19 +89,20 @@
 <h1>Introduction<a class="headerlink" href="#introduction" title="Link to this heading"></a></h1>
 <img alt="_images/animationspe11a.gif" src="_images/animationspe11a.gif" />
 <p>This documentation describes the content of the <strong>pyopmspe11</strong> package.
-The numerical studies are performed using the <a class="reference external" href="https://opm-project.org/?page_id=19">Flow</a> simulator.</p>
+The numerical studies are performed using the <a class="reference external" href="https://opm-project.org/?page_id=19">OPM Flow simulator</a>.</p>
 <section id="concept">
 <h2>Concept<a class="headerlink" href="#concept" title="Link to this heading"></a></h2>
-<p>Simplified and flexible framework for the three cases in the SPE Comparative Solution Project
+<p>Simplified and flexible framework for the three cases in the <a class="reference external" href="https://www.spe.org/en/csp/">SPE Comparative Solution Project</a>
 via a <a class="reference internal" href="configuration_file.html"><span class="doc">configuration file</span></a>:</p>
 <ul class="simple">
 <li><p>Set the path to the OPM Flow simulator and simulator flags.</p></li>
-<li><p>Set the grid type (cartesian, tensor, or corner-point grid) and the number of cells.</p></li>
+<li><p>Set the grid type (Cartesian, tensor, or corner-point grid) and the number of cells.</p></li>
 <li><p>Set the rock and fluid properties.</p></li>
-<li><p>Set the well or sources locations and injection schedule.</p></li>
-<li><p>After execution. generates the data in the same format as requested in the benchmark.</p></li>
-<li><p>In addition, generates .png figures for quick inspection.</p></li>
-<li><p>Also, generates figures for comparison between runs (i.e., to assess sensitivities).</p></li>
+<li><p>Set the wells or sources locations and define the injection schedule.</p></li>
+<li><p>Select the functionality (e.g., generate only the input decks, run the whole framework).</p></li>
+<li><p>The framework generates the data in the same format as requested in the benchmark.</p></li>
+<li><p>In addition, it generates .png figures for quick inspection of the results.</p></li>
+<li><p>Also, it generates figures for comparison between runs (i.e., to assess sensitivities).</p></li>
 </ul>
 </section>
 <section id="overview">

docs/pyopmspe11.core.pyopmspe11.html

@@ -85,7 +85,7 @@
 
   <section id="module-pyopmspe11.core.pyopmspe11">
 <span id="pyopmspe11-core-pyopmspe11-module"></span><h1>pyopmspe11.core.pyopmspe11 module<a class="headerlink" href="#module-pyopmspe11.core.pyopmspe11" title="Link to this heading"></a></h1>
-<p>Main script</p>
+<p>Main script for pyopmspe11</p>
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.core.pyopmspe11.load_parser">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.core.pyopmspe11.</span></span><span class="sig-name descname"><span class="pre">load_parser</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.core.pyopmspe11.load_parser" title="Link to this definition"></a></dt>
@@ -101,7 +101,7 @@
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.core.pyopmspe11.pyopmspe11">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.core.pyopmspe11.</span></span><span class="sig-name descname"><span class="pre">pyopmspe11</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.core.pyopmspe11.pyopmspe11" title="Link to this definition"></a></dt>
-<dd><p>Main function</p>
+<dd><p>Main function for the pyopmspe11 executable</p>
 </dd></dl>
 
 </section>

docs/pyopmspe11.utils.inputvalues.html

@@ -89,44 +89,50 @@
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.utils.inputvalues.check_deck">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.utils.inputvalues.</span></span><span class="sig-name descname"><span class="pre">check_deck</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dic</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.utils.inputvalues.check_deck" title="Link to this definition"></a></dt>
-<dd><p>Write unsupported features to the terminal if flow from release is used</p>
+<dd><p>Write unsupported features to the terminal if Flow from release is used</p>
+<dl class="simple">
+<dt>Args:</dt><dd><p>dic (dict): Global dictionary</p>
+</dd>
+<dt>Returns:</dt><dd><p>dic (dict): Modified global dictionary</p>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.utils.inputvalues.process_input">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.utils.inputvalues.</span></span><span class="sig-name descname"><span class="pre">process_input</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dic</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">in_file</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.utils.inputvalues.process_input" title="Link to this definition"></a></dt>
-<dd><p>Function to process the input file</p>
-<dl class="simple">
-<dt>Args:</dt><dd><p>dic (dict): Global dictionary with required parameters
-in_file (str): Name of the input text file</p>
+<dd><p>Process the configuration file</p>
+<dl>
+<dt>Args:</dt><dd><p>dic (dict): Global dictionary</p>
+<p>in_file (str): Name of the input text file</p>
 </dd>
-<dt>Returns:</dt><dd><p>dic (dict): Global dictionary with new added parameters</p>
+<dt>Returns:</dt><dd><p>dic (dict): Modified global dictionary</p>
 </dd>
 </dl>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.utils.inputvalues.readthefirstpart">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.utils.inputvalues.</span></span><span class="sig-name descname"><span class="pre">readthefirstpart</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lol</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dic</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.utils.inputvalues.readthefirstpart" title="Link to this definition"></a></dt>
-<dd><p>Function to process the lines from the flow executable and model parameters</p>
-<dl class="simple">
-<dt>Args:</dt><dd><p>lol (list): List of lines read from the input file
-dic (dict): Global dictionary with required parameters</p>
+<dd><p>Process the lines from the flow executable and model parameters</p>
+<dl>
+<dt>Args:</dt><dd><p>lol (list): List of lines read from the input file</p>
+<p>dic (dict): Global dictionary</p>
 </dd>
-<dt>Returns:</dt><dd><p>dic (dict): Global dictionary with new added parameters</p>
+<dt>Returns:</dt><dd><p>dic (dict): Modified global dictionary</p>
 </dd>
 </dl>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.utils.inputvalues.readthesecondpart">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.utils.inputvalues.</span></span><span class="sig-name descname"><span class="pre">readthesecondpart</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lol</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dic</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.utils.inputvalues.readthesecondpart" title="Link to this definition"></a></dt>
-<dd><p>Function to process the lines from the saturation functions until the end</p>
-<dl class="simple">
-<dt>Args:</dt><dd><p>lol (list): List of lines read from the input file
-dic (dict): Global dictionary with required parameters</p>
+<dd><p>Process the lines from the saturation functions until the end</p>
+<dl>
+<dt>Args:</dt><dd><p>lol (list): List of lines read from the input file</p>
+<p>dic (dict): Global dictionary</p>
 </dd>
-<dt>Returns:</dt><dd><p>dic (dict): Global dictionary with new added parameters</p>
+<dt>Returns:</dt><dd><p>dic (dict): Modified global dictionary</p>
 </dd>
 </dl>
 </dd></dl>