Merge pull request #409 from ESSS/fb-fix-conda-doc

Improve documentation

docs/source/plugins/01_quick_start.rst

@@ -18,16 +18,15 @@ the official docs <https://www.python.org/downloads/>`_.
 
 .. note::
 
-    It is recommended that you install the |sdk| using the conda package manager. With the commands below, a conda
-    environment would be created with |sdk| installed on it.
+    It is recommended to install the |sdk| using the conda package manager. The following commands will create a conda environment with |sdk| installed.
 
     .. code-block:: bash
 
-        >>> conda env create -n sdk_env
+        >>> conda create -n sdk_env
         >>> conda activate sdk_env
         >>> pip install alfasim-sdk
 
-    Another approach could be adding a ``environment.yml`` to your project and declare the ``alfasim-sdk`` inside the ``pip`` dependencies.
+    Alternatively, an ``environment.yml`` can be added to your project and ``alfasim-sdk`` can be declared at ``pip`` dependencies.
 
     For more details, see `Getting started with conda <https://conda.io/projects/conda/en/latest/user-guide/getting-started.html>`_.
 
@@ -100,16 +99,16 @@ After the execution of the :program:`new` command the generated plugin project w
 The highlights here are for:
 
 :plugin.yaml: File with all information about the plugin that will be used by |alfasim|.
-:myplugin.py: Implementation of the hooks for customization of the UI interface, or the solver configuration hooks.
+:myplugin.py: Implementation of the hooks for customization of the user interface or the solver configuration hooks.
 :myplugin.c:  Implementation of the hooks for customization of solver.
 
-Check out the :ref:`Plugin Structure section <plugin_structure-section>` for more details about how the folder and files are structured, and
-also, check the :ref:`plugin-by-example-section` that shows how to create simple plugins that make use of the `User Interface Hooks` and the `Solver Hooks`.
+Refer to the :ref:`Plugin Structure section <plugin_structure-section>` for more details about how the folder and files are structured.
+The section :ref:`plugin-by-example-section` shows how to create simple plugins that make use of the `User Interface Hooks` and the `Solver Hooks`.
 
 Invoke
 ------
 
-From version 0.17.0 onwards, |sdk| started using `pyinvoke`_ tasks in order facilitate and standardize the plugins development process
+Since version 0.17.0, |sdk| started using `pyinvoke`_ tasks in order facilitate and standardize the plugins development process
 using pre-defined tasks. A standard ``tasks.py`` file is generated automatically by the :program:`new` command, which can be customized by the user if needed.
 
 To list the tasks available, use:
@@ -124,8 +123,8 @@ To list the tasks available, use:
 Creating a package
 ------------------
 
-From the root directory of the plugin, execute the command `invoke package`.
-This command will compile your C/C++ implementation and include the shared libraries inside a `artifacts` directory and
+From the plugin root directory, execute the command `invoke package`.
+This command will compile your C/C++ implementation and include the shared libraries inside an `artifacts` directory and
 the generated plugin on the root directory with the extension `hmplugin`.
 
 .. code-block:: bash
@@ -171,18 +170,18 @@ Installing the plugin
 ---------------------
 
 With :file:`myplugin.hmplugin` file, it is now possible to install it on |alfasim| application.
-From the menu bar select the `Plugin Manager` option, as illustrated in the figure below:
+At the menu bar select the `Plugin Manager` option, as illustrated in the figure below:
 
 .. image:: /_static/images/quick_start/menu_bar.png
 
-In the `Plugin Manager` windows, install :file:`myplugin.hmplugin` file plugin.
+In the `Plugin Manager` window, install :file:`myplugin.hmplugin` file plugin.
 
 .. image:: /_static/images/quick_start/plugin_manager_empty.png
 
-By clicking on the plugin name, it is possible to visualize the content from the :file:`README.md` file.
+By clicking on the plugin name, it is possible to visualize the content of the :file:`README.md` file.
 
 .. image:: /_static/images/quick_start/plugin_manager_with_plugin.png
 
-Restart the application and check the recently installed plugin available over the :guilabel:`Tree`.
+Restart the application and check the recently installed plugin available at the :guilabel:`Tree`.
 
 .. image:: /_static/images/quick_start/tree_with_plugin.png

docs/source/plugins/02_alfasim_sdk_by_example.rst

@@ -5,8 +5,8 @@ Plugin by Example
 =================
 
 
-In this section, we will continue to customize the plugin created from the previous section,
-this plugin will calculate the oil velocity to the power of a given exponent provided by the user from the user interface.
+In this section, we will continue to customize the plugin created from the previous section.
+This plugin will calculate the oil velocity to the power of a given exponent provided by the user from the user interface.
 
 The following equation describes the plugin:
 
@@ -26,11 +26,11 @@ The following equation describes the plugin:
 
 For this, we will need to:
 
-#. Create a simple input, on the user interface.
+#. Create a simple input on the user interface.
 #. Add a secondary variable, to keep track of the value.
 #. Retrieve the input data on the :py:func:`HOOK_INITIALIZE<alfasim_sdk._internal.hook_specs.initialize>`.
 #. Save the input data on a plugin internal data.
-#. Get the oil velocity from the solver, during run-time.
+#. Get the oil velocity from the solver during run-time.
 #. Export the value into the created/registered plugin secondary variable.
 
 
@@ -54,7 +54,7 @@ the locations where a custom model can be inserted using the hook |gui_hook|.
 For this example we will use a :py:func:`~alfasim_sdk.data_model` entry over the Tree,
 using a :py:class:`~alfasim_sdk.Quantity` field to get exponent value from the user.
 
-The hook |gui_hook| needs to be implemented on the :file:`myplugin.py`, located on :file:`myplugin/src/python` folder.
+The hook |gui_hook| needs to be implemented in the :file:`myplugin.py`, found in :file:`myplugin/src/python` folder.
 
 .. rubric:: Implementation of :file:`myplugin.py`
 
@@ -74,7 +74,7 @@ The hook |gui_hook| needs to be implemented on the :file:`myplugin.py`, located
 
 
 Notice that only models that are returned by the hook :py:func:`~alfasim_sdk._internal.hook_specs_gui.alfasim_get_data_model_type`
-will be included on the user interface of |alfasim|.
+will be included in the user interface of |alfasim|.
 
 The image below illustrates the application with the output from the snippet above.
 
@@ -90,18 +90,18 @@ And for more detail about the available models, check the section :ref:`api-mode
 Solver Configuration
 --------------------
 
-|sdk| provides hooks to customize the settings of the application that configures the solver internally,
-some of these configurations are:
+|sdk| provides hooks to customize the settings of the application that configures the solver internally.
+Some of these configurations are:
 
 - Creation/Registration of new secondary variables
 - Creation of new phases/fields/layers.
 - Update of default phases and layers from the application.
 
-For this example, a new |s_variable| will be created, to track the oil velocity to the power of a custom value provided from the user.
+For this example, a new |s_variable| will be created to track the oil velocity to the power of a custom value provided by the user.
 
 
 A *Secondary Variable* is a variable that can be calculated along the `Network`. Also, if configured as external, this
-variable will be set an Output, and will be available within the Trends and Profiles plots.
+variable will be set as an Output, and will be available within the Trends and Profiles plots.
 
 To create these variables, the hook |s_variable_hook| must be implemented in the :file:`myplugin.py` file.
 
@@ -130,7 +130,7 @@ To create these variables, the hook |s_variable_hook| must be implemented in the
         ]
 
 
-The image below illustrates the application with the output from the snippet above. To access that window, first select the desired structure
+The image below illustrates the application with the output from the snippet above. To access the configuration window, first select the desired structure
 then go to Output Options at the left side tree and add/edit a trend.
 
 .. image:: /_static/images/plugin_example/secondary_variable_trend_output.png
@@ -144,14 +144,14 @@ Hooks for Solver
 |sdk| provides hooks that can customize the ``Solver`` behavior, this customization are implemented in C/C++ and can
 make use of the :ref:`ALFAsim-SDK C/C++ API <sdk_api>` in order to fetch information from the application.
 
-At this point, we are going to implement the :ref:`solver_hooks` that updates the secondary variable declared from
+At this point, we are going to implement the :ref:`solver_hooks` that updates the secondary variable declared in
 :file:`myplugin.py` file and retrieve the ``Oil Velocity`` from the |alfasim|'s Solver.
 
-First, we need to implement two mandatory hooks, the :py:func:`HOOK_INITIALIZE <alfasim_sdk._internal.hook_specs.initialize>` and
+First, we need to implement two mandatory hooks: the :py:func:`HOOK_INITIALIZE <alfasim_sdk._internal.hook_specs.initialize>` and
 the :py:func:`HOOK_FINALIZE <alfasim_sdk._internal.hook_specs.finalize>`
 
 With them it is possible to initialize any custom data (to store any important information) for internal use. Also it is
-needed to load and unload the |sdk| API, in which will allows the plugin to use the API in any implemented `hook`.
+necessary to load and unload the |sdk| API, allowing the plugin to use the API in any implemented `hook`.
 
 .. rubric::  Implementation of :file:`myplugin.cpp`
 
@@ -221,7 +221,7 @@ needed to load and unload the |sdk| API, in which will allows the plugin to use
         return OK;
     }
 
-Then, since the plugin wants to calculate its own secondary variable, the
+Then, since the plugin aims to calculate its own secondary variable, the
 :py:func:`HOOK_UPDATE_PLUGINS_SECONDARY_VARIABLES <alfasim_sdk._internal.hook_specs.update_plugins_secondary_variables>` must be implemented.
 As can be seen in the example below, to retrieve the velocity of the continuous oil field
 it is necessary to use the :cpp:func:`get_simulation_array` API function.
@@ -301,7 +301,7 @@ it is necessary to use the :cpp:func:`get_simulation_array` API function.
     }
 
 
-The image below illustrates the output from the solver, when running the plugin created in this section with the given
+The image below illustrates the output from the solver when running the plugin created in this section with the given
 network. That information can be seen by selecting the desired structure and opening the Trend plot window.
 
 .. image:: /_static/images/plugin_example/output_graph.png

docs/source/plugins/03_plugin_structure.rst

@@ -3,7 +3,7 @@
 Plugins Structure
 =================
 
-As mentioned in :ref:`quick-start-section`, the |sdk| package has some utilities to help in the process to create
+As mentioned in :ref:`quick-start-section`, the |sdk| package has some utilities to help in the process of creating
 a plugin file.
 
 First, to create the plugin use :program:`new`:
@@ -21,10 +21,8 @@ First, to create the plugin use :program:`new`:
 Pyinvoke tasks
 --------------
 
-Except for creating the plugin structure, all other activities that you might want to perform, you will use ``pyinvoke`` tasks.
-
-Below there is detailed list on what they are meant to do. However, in general, the tasks that you will use the most are ``compile``,
-``package`` and ``update``.
+Once the plugin structure is created, you can perform all necessary activities using ``pyinvoke`` tasks, with ``compile``, ``package``  and ``update`` beeing the
+most commonly used during plugin development. Below you can find a list of all available along with their descriptions.
 
 .. invoke::
    :module: alfasim_sdk.default_tasks

docs/source/plugins/04_application_hooks.rst

@@ -7,8 +7,7 @@ The application hooks allow plugins to add custom models or custom checks in the
 To add an application hook it is necessary to implement the given hook in a python file that is
 already available on your plugin project folder.
 
-As an example, if the ``alfasim-sdk new`` command was created with the name ``myplugin``, the necessary file to
-be customized will be located on: :menuselection:`myplugin --> src --> python --> myplugin.py`
+For example, after executing the command ``alfasim-sdk new myplugin``, the file ``myplugin.py``, located at :menuselection:`myplugin --> src --> python` should be customized.
 
 .. contents::
     :depth: 3

docs/source/plugins/05_solver_config_hooks.rst

@@ -33,8 +33,8 @@ the hook listed below, the plugin can:
  - Add/update layers
 
 .. note::
-    For each new added ``field`` is considered a mass conservation equation and for each new added ``layer`` is considered
-    a momentum conservation and an energy conservation equations, depending on the energy model used at |alfasim|.
+    For each new added ``field``, an additional mass conservation equation is considered. For each new added ``layer``, an additional  momentum  equation is considered.
+    Depending on the energy model used at |alfasim|, an additional energy equation can be considered as well.
 
 .. autofunction:: alfasim_sdk._internal.hook_specs_gui.alfasim_configure_fields
 
@@ -44,7 +44,7 @@ the hook listed below, the plugin can:
 
 
 In order to complement the :py:class<alfasim-sdk.HydrodynamicModelType> customization, it is possible to inform |alfasim| which phases
-(added from plugin or not) will have the state variables calculated by plugin.
+(added by the plugin or not) will have the state variables calculated by plugin.
 
 .. autofunction:: alfasim_sdk._internal.hook_specs_gui.alfasim_get_phase_properties_calculated_from_plugin