revise text

docs/source/development/architecture.rst

@@ -4,19 +4,19 @@
 Architecture
 ************************
 
-Wizards UI
+Wizards-like UI
 ==========
 
-QuantumESPRESSO app uses the Wizards UI, which divides one calculation into four steps.
-Each step may contain several sections (panels), as shown below.
+QuantumESPRESSO app uses the [Wizards-like UI design](https://en.wikipedia.org/wiki/Wizard_(software)), which divides one calculation into four steps.
+Each step may contain several sections (panels), as shown in the figure below.
 
 .. image:: ../_static/images/plugin_step.png
 
 Parameter transfer between steps
 ---------------------------------
 
-The data is passed to the next step by linking it to the corresponding ``trail`` of the step.
-For example, the ``confirmed_structure`` of step 1 is linked to the ``input_structure`` ``trail`` of step 2.
+The data is passed to the next step by linking it to the corresponding ``trait`` of the step widget.
+For example, the ``confirmed_structure`` of step 1 links to the ``input_structure`` trait of step 2.
 
 .. code:: python
 
@@ -25,9 +25,7 @@ For example, the ``confirmed_structure`` of step 1 is linked to the ``input_stru
             (self.configure_qe_app_work_chain_step, "input_structure"),
         )
 
-In the configuration step, there are several panels.
-The parameters from these panels are generated and stored as a dictionary,
-which is linked to the ``input_parameters`` ``trail`` of the next submit step.
+Each step widget can contains several panels. In the configuration step, the parameters from the panels are generated and stored as a dictionary, which is linked to the ``input_parameters`` trait of the next submit step.
 The dictionary has the following structure:
 
 .. code:: python
@@ -61,21 +59,20 @@ Plugin
 ======
 
 QuantumESPRESSO app supports running multiple properties (bands, pdos, etc.) calculations in one app.
-Please take into account the following facts:
+The individual properties to be developed and seamlessly integrated into the QuantumESPRESSO app as plugins. This integration is made possible due to several key aspects:
 
 - the configuration for a property calculation has its settings unrelated to other properties.
 - the sub-workchain of the properties can be run independently.
-- the analysis of the results of the properties is also independent.
+- the analysis of the results of the properties is independent.
 
-Thus, we can develop a property separately and integrate it into the QuantumESPRESSO app as a plugin.
 Each plugin responsible for one property calculation.
-For example, we could create a PDOS plugin, including its settings, workchain, and result analysis.
-The GUI of the PDOS plugin is only loaded when the user selects to run the PDOS property.
+For instance, we could create a PDOS plugin, including its settings, workchain, and result analysis.
+The GUI of the PDOS plugin is only loaded when the user selects to run it.
 Here is an example, where two new setting panels are shown when the user selects to run the properties.
 
 .. figure:: ../_static/images/plugin_example.png
 
 
-A QuantumESPRESSO app plugin will typically register new panels (setting, result), and workchain to extend the app's functionality.
+A QuantumESPRESSO app plugin will typically register new panels (setting, result), and workchain to extend the functionality of the app.
 The plugin design makes the QuantumESPRESSO app more modularized and pluggable.
-So the developer can maintain their plugin as a separate folder in the QuantumESPRESSO app (even a separate package).
+Consequently, developers have the flexibility to manage their plugins in a distinct folder within the QuantumESPRESSO application's codebase, or they may choose to maintain it as an independent package.

docs/source/development/index.rst

@@ -4,7 +4,7 @@
 Developer guide
 ###################
 
-This guide explains how to extend the functionality of the app.
+This guide explains the architecture of the application and how to extend the functionality of the app by integrating new features through plugin development.
 
 .. toctree::
     :maxdepth: 1

docs/source/development/plugin.rst

@@ -10,20 +10,12 @@ A QuantumESPRESSO app plugin will typically register new panels (setting, result
 Your First Plugin
 ================================
 
-Here is the simplest plugin to print the formula of the input structure:
+Here is the an example plugin to print the formula of the input structure:
 
 Outline
 -----------------------
-A  :class:`~aiidalab_qe.common.panel.Outline` will add an item in the properties section of the workflow panel.
-For this example, we'll add the ``Hello World`` item, as shown below.
-
-
-.. image:: ../_static/images/plugin_outline.png
-    :align: center
-
-
-
-The **Outline** will be shown as a checkbox.
+A  :class:`~aiidalab_qe.common.panel.Outline` widget can add an item in the properties section of the workflow panel.
+In this example, we add the ``Hello World`` outline.
 
 .. code-block:: python
 
@@ -32,19 +24,24 @@ The **Outline** will be shown as a checkbox.
     class Outline(OutlinePanel):
         title = "Hello World"
 
+The outline is a checkbox, as shown below.
 
+.. image:: ../_static/images/plugin_outline.png
+    :align: center
 
 Setting
 -----------------------
-A  :class:`~aiidalab_qe.common.panel.Panel` will register a new panel in the configuration step, e.g. the ``Hello world`` panel.
-
+A setting :class:`~aiidalab_qe.common.panel.Panel` widget will register a new panel in the configuration step, e.g. the ``Hello world`` panel.
 
 .. image:: ../_static/images/plugin_setting.png
 
-In this class, one can add widgets (e.g. Float, Int) to the GUI.
+In this class, you can add widgets to the GUI.
 The values of these widgets will be used in the WorkChain.
-One needs to override the ``get_panel_value`` method to tell QuantumESPRESSO app how to use the values from the widgets.
-One also need to override the ``set_panel_value`` method to tell QuantumESPRESSO app how to reload the panel values from previous calculation, and the ``reset`` method to reset the panel to the default values.
+you need to override the the following methods:
+
+- ``get_panel_value`` method to tell the app how to use the values from the widgets.
+- ``set_panel_value`` method to tell the app how to reload the panel values from the previous calculation.
+- ``reset`` method to reset the panel to the default values.
 
 .. code-block:: python
 
@@ -73,13 +70,16 @@ One also need to override the ``set_panel_value`` method to tell QuantumESPRESSO
 
 Result
 -----------------------
-A  :class:`~aiidalab_qe.common.panel.ResultPanel` will register a new panel in the Results Step, e.g., the ``Hello world`` panel.
+A  :class:`~aiidalab_qe.common.panel.ResultPanel` will register a new panel in the results step. The ``Hello world`` panel is shown below:
 
 
 .. image:: ../_static/images/plugin_result.png
 
-In this class, one needs to specific the `workchain_labels` to tell QuantumESPRESSO app which workchain the panel is for.
-Then, one needs to implement the ``_update_view`` method to tell QuantumESPRESSO app how to show the results of the workchain.
+In this class, you need to:
+
+- specify the `workchain_labels` to tell the app which workchains the panel is intended for.
+- implement the ``_update_view`` method to tell the app how to show the results of the workchain.
+
 The output of the workchain will be stored in ``self.outputs.hello_world``.
 For example, the ``name`` and ``structure`` are the outputs of the ``HelloWorldWorkChain``.
 
@@ -103,7 +103,7 @@ For example, the ``name`` and ``structure`` are the outputs of the ``HelloWorldW
 
 WorkChain and Builder
 -----------------------
-One needs to implement a ``get_builder`` function to tell QuantumESPRESSO app how to use the input parameters from the GUI.
+you need to implement a ``get_builder`` function to tell QuantumESPRESSO app how to use the input parameters from the GUI.
 
 The `parameters` passed to the `get_builder` function has the following structure:
 
@@ -134,7 +134,7 @@ The `parameters` passed to the `get_builder` function has the following structur
         "plugin_1": {...},
     }
 
-One needs to decide which parameters are needed for the workchain, and how to use them.
+you need to decide which parameters are needed for the workchain, and how to use them.
 For example, the ``HelloWorldWorkChain`` needs the ``name`` parameter, which is defined in the ``Setting`` panel.
 The ``get_builder`` function will return a ``builder`` for the ``HelloWorldWorkChain``.
 The ``builder`` will be used to submit the workchain.
@@ -166,7 +166,7 @@ Then register the workchain and builder in the `workchain_and_builder` dict, so
 
 Entry point
 -----------------------
-Finally, one needs to register the entry point of the plugin. Here is the entry point for this plugin.
+Finally, you need to register the entry point of the plugin. Here is the entry point for this plugin.
 
 .. code-block:: python
 
@@ -181,7 +181,7 @@ Finally, one needs to register the entry point of the plugin. Here is the entry
 Install the plugin
 -----------------------
 To install the plugin, you can creating a new package or adding it to the `aiidalab_qe.plugins` folder.
-One needs to add the path of ``hello_world`` to ``entry_points`` inside the setup file.
+you need to add the path of ``hello_world`` to ``entry_points`` inside the setup file.
 
 .. code-block:: python
 
@@ -193,10 +193,10 @@ One needs to add the path of ``hello_world`` to ``entry_points`` inside the setu
 
 **Bringing It All Together**, You can find all the code above in this github repository: https://github.com/superstar54/aiidalab-qe-hello-world
 
-Your second plugin
+Advanced usage
 ================================
-One plugin does not need to register all the items (settings, workchain, results).
-The panel in each step is pluggable, which means you could only register one item in a plugin.
+A plugin does not need to register all the items (settings, workchain, results).
+The panel in each step is pluggable, which means you could only register you item in a plugin.
 For example, you can only add a new `Result` panel without doing any property calculation.
 The built-in `electronic_structure` plugin only has a result panel, which needs the result from both `pdos`` and `bands`` plugins.
 This is set by the `workchain_labels` attribute.
@@ -217,8 +217,8 @@ Here is the entry point for this plugin.
         "result": Result,
     }
 
-Your third plugin
-================================
+Structure importer and editor
+------------------------------
 The plugin API also allows the user to add a new structure importer and editor:
 
 - add structure `importer` specific for particular structures, e.g. surface,  adsorbate.
@@ -241,4 +241,4 @@ Here is the example for such plugin.
 Further Reading
 ================================
 QuantumESPRESSO app comes with built-in plugins, which can be found in the ``aiidalab_qe.plugins`` folder.
-You can also use them as templates to create your own plugins.
+You can also use them as a start point to create your own plugins.