Tutorial mandi/style part 0 (#175)

* Reorder the `-h` and `--help` option description.

* Convert tip about jmol from note to tip and reword.

* Mention `wget` in context of instructions to download script.

* Sentences should start capitalized.

* Reword instructions about moving to different computer.

* Reword instructions about missing partner machine.

* Use single quotes in 'demo_calcjob.py' script consistently.

* Reword instructions about second ssh terminal connection.

* Reword troubleshooting section.

* Reword instructions about ssh config.

* Add note about ignoring the ssh port forwarding warnings.

Co-Authored-By: Casper Welzel Andersen <43357585+CasperWA@users.noreply.github.com>

docs/pages/2019_IIT_Mandi_India/sections/first_taste.rst

@@ -19,7 +19,7 @@ Here are some first tasks for you:
 
  * The ``verdi`` command supports **tab-completion**:
    In the terminal, type ``verdi``, followed by a space and press the 'Tab' key twice to show a list of all the available sub commands.
- * For help on any ``verdi`` command, simply append the ``--help/-h`` flag:
+ * For help on any ``verdi`` command, simply append the ``-h`` or ``--help`` flag:
 
    .. code:: bash
 
@@ -52,23 +52,24 @@ Each piece of data in AiiDA gets a PK number (a "primary key") that identifies i
 The PK is printed to screen by the ``verdi data structure import`` command.
 **Mark down the PK for your structure and use it to replace the <PK> placeholders in what follows.**
 
-.. note::
+.. tip::
 
    You can view the structure either `online <http://crystallography.net/cod/9008565.html>`_
-   or use ``jmol 9008565.cif`` locally.
+   or by executing the ``jmol 9008565.cif`` command on the virtual machine (or preferably on your local machine for better performance in case that ``jmol`` is installed).
 
 .. Let jason/jianxing test speed of SSH forwarding - potentially mention jupyter
 
 The following short python script sets up a self-consistent field calculation for the Quantum ESPRESSO code:
 
 .. literalinclude:: include/snippets/demo_calcjob.py
 
-Download the :download:`demo_calcjob.py <include/snippets/demo_calcjob.py>` script to your working directory.
+Download the :download:`demo_calcjob.py <include/snippets/demo_calcjob.py>` script using ``wget`` to your working directory.
 It contains a few placeholders for you to fill in:
 
- #. the VM already has a number of codes preconfigured. Use ``verdi code list`` to find the label for the "PW" code and use it in the script.
- #. replace the PK of the structure with the one you obtained
- #. the VM already contains a number of pseudopotential families. Replace the PP family name with the one for the "SSSP efficiency" library found via ``verdi data upf listfamilies``.
+ #. The VM already has a number of codes preconfigured. Use ``verdi code list`` to find the label for the "PW" code and use it in the script.
+ #. Replace the PK of the structure with the one you noted down earlier.
+ #. The VM already a number of pseudopotential families installed.
+    Replace the PP family name with the one for the "SSSP efficiency" library found via ``verdi data upf listfamilies``.
 
 Then submit the calculation using:
 
@@ -133,12 +134,16 @@ A few questions you could answer using these commands (optional)
  * How many SCF iterations were needed for convergence?
  * How long did Quantum ESPRESSO actually run (wall time)?
 
+.. tip::
+
+    Use the ``grep`` command to filter the terminal output by keywords, e.g., ``verdi calc job res 175 | grep wall_time``.
+
 Moving to a different computer
 ------------------------------
 
-Now, this Quantum ESPRESSO calculation ran on your (virtual) machine.
-This is fine for tests, but for production calculations you'll typically want to run on a remote compute cluster.
-In AiiDA, moving a calculation from one computer to another means changing one line of code.
+The Quantum ESPRESSO calculation we just ran, was directly executed on the virtual machine.
+This is fine for tests, but production calculations should typically be run on a remote compute cluster.
+With AiiDA, moving a calculation from one computer to another means changing one line of code.
 
 For the purposes of this tutorial, you'll run on your neighbor's computer.
 Ask your neighbor for the IP address of their VM.
@@ -152,8 +157,8 @@ Then, download the :download:`neighbor.yml <include/configuration/neighbor.yml>`
 
 .. note::
 
-    If you're completing this tutorial at a later time and have no partner machine,
-    simply use "localhost" instead of the IP address.
+    If you do not have a partner machine available, for example because you are completing this
+    tutorial at a later time, simply use "localhost" instead of the IP address.
 
 AiiDA is now aware of the existence of the computer but you'll still need to let AiiDA
 know how to connect to it.

docs/pages/2019_IIT_Mandi_India/sections/include/snippets/demo_calcjob.py

@@ -2,7 +2,7 @@
 from aiida.orm.nodes.data.upf import get_pseudos_from_structure
 from aiida.engine import submit
 
-code = Code.get_from_string("<CODE LABEL>")  # REPLACE <CODE LABEL>
+code = Code.get_from_string('<CODE LABEL>')  # REPLACE <CODE LABEL>
 builder = code.get_builder()
 
 # Select structure

docs/pages/2019_IIT_Mandi_India/sections/setup.rst

@@ -34,7 +34,7 @@ It's recommended for you to place the ssh key you received in a folder dedicated
    ``chmod 600 ~/.ssh/aiida_tutorial_NUM``. You can check check with ``ls -l``
    that the permissions of this file are now ``-rw-------``.
 
-After that ssh key is in place, you can add the following block your ``~/.ssh/config`` file:
+After the ssh key files are in place, add the following block to your ``~/.ssh/config`` file:
 
 .. code:: bash
 
@@ -137,13 +137,13 @@ In order to connect to the jupyter notebook server:
  - Open a web browser **on your laptop** and paste the URL.
  - You will see a list of folders on your personal VM.
 
-While keeping the first ``ssh`` connection running, open another ``ssh`` connection in a second terminal and type ``workon aiida`` here too.
-**This** terminal is the one we will actually use in this tutorial.
+While keeping the first ``ssh`` connection running, open a second ``ssh`` connection in a separate terminal and execute ``workon aiida`` there as well.
+We will use the second terminal to directly interact with the virtual machine on the command line, while we use the first one to only serve the jupyter notebook.
 
 .. note::
 
-   Our SSH configuration assumes that ``jupyter`` will serve the notebooks on port 8888.
-   If you want to serve notebooks on different ports, you'll also need to adjust the SSH configuration.
+    You can safely ignore all warnings related to port forwarding when opening a second ssh connection.
+    Those are caused by the fact that the ports are now already in use which in this context is perfectly fine.
 
 
 .. _2019_mandi_setup_downloading_files:
@@ -157,16 +157,17 @@ In particular, when running the tutorial on a Linux VM, copy the link address an
 
 .. code:: bash
 
-   wget <LINK>
+   wget <URL>
 
-where you replace ``<LINK>`` with the actual HTTPS link copied from the tutorial text in your browser.
-This will download the file in your current directory.
+where you replace ``<URL>`` with the actual HTTPS URL copied from the tutorial text in your browser.
+This will download the file to the current directory.
 
 
 Troubleshooting
 ---------------
 
--  If you get errors ``ImportError: No module named aiida`` or ``No command ’verdi’ found``, double check that you have loaded the virtual environment with ``workon aiida`` before launching ``python``, ``ipython`` or the ``jupyter`` notebook server.
+-  If you encounter errors such as ``ImportError: No module named aiida`` or ``No command ’verdi’ found``, double check that you have loaded the virtual environment with ``workon aiida`` before launching ``python``, ``ipython`` or the ``jupyter`` notebook server.
+   Your command line prompt should start with ``(aiida)``, e.g., ``(aiida) max@workhorse:~$``.
 
 -  If your browser cannot connect to the jupyter notebook server, check that you have correctly configured SSH tunneling/forwarding as described above.
    Keep in mind that you need to start the jupyter server from the terminal connected to the VM, while the web browser should be opened locally on your laptop.