move the entries about using the Python module into its own (sub) toctree

doc/src/Python_ext.rst

@@ -1,16 +1,19 @@
 Extending the library and Python interface
 ******************************************
 
-As noted above, these Python class methods correspond one-to-one with
+As noted previously, the Python class methods correspond one-to-one with
 the functions in the LAMMPS library interface in ``src/library.cpp`` and
-``library.h``.  This means you can extend the Python wrapper via the
+``library.h``.  This means you can extend the Python wrapper by
-following steps:
+following these steps:
 
 * Add a new interface function to ``src/library.cpp`` and
   ``src/library.h``.
 * Rebuild LAMMPS as a shared library.
 * Add a wrapper method to ``python/lammps.py`` for this interface
   function.
+* Define the corresponding ``argtypes`` list and ``restype``
+  in the ``lammps.__init__()`` function.
+* Re-install the shared library and the python module, if needed
 * You should now be able to invoke the new interface function from a
   Python script.
 

doc/src/Python_head.rst

@@ -10,14 +10,6 @@ together.
    Python_overview
    Python_install
    Python_run
-   Python_create
-   Python_execute
-   Python_properties
-   Python_atoms
-   Python_objects
-   Python_scatter
-   Python_neighbor
-   Python_config
    Python_module
    Python_ext
    Python_call

doc/src/Python_launch.rst

@@ -0,0 +1,108 @@
+Running LAMMPS and Python in serial
+-----------------------------------
+
+To run a LAMMPS in serial, type these lines into Python
+interactively from the ``bench`` directory:
+
+.. code-block:: python
+
+   >>> from lammps import lammps
+   >>> lmp = lammps()
+   >>> lmp.file("in.lj")
+
+Or put the same lines in the file ``test.py`` and run it as
+
+.. code-block:: bash
+
+   $ python3 test.py
+
+Either way, you should see the results of running the ``in.lj`` benchmark
+on a single processor appear on the screen, the same as if you had
+typed something like:
+
+.. code-block:: bash
+
+   lmp_serial -in in.lj
+
+Running LAMMPS and Python in parallel with MPI
+----------------------------------------------
+
+To run LAMMPS in parallel, assuming you have installed the
+`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
+:ref:`python_install_mpi4py`, create a ``test.py`` file containing these lines:
+
+.. code-block:: python
+
+   from mpi4py import MPI
+   from lammps import lammps
+   lmp = lammps()
+   lmp.file("in.lj")
+   me = MPI.COMM_WORLD.Get_rank()
+   nprocs = MPI.COMM_WORLD.Get_size()
+   print("Proc %d out of %d procs has" % (me,nprocs),lmp)
+   MPI.Finalize()
+
+You can run the script in parallel as:
+
+.. code-block:: bash
+
+   $ mpirun -np 4 python3 test.py
+
+and you should see the same output as if you had typed
+
+.. code-block:: bash
+
+   $ mpirun -np 4 lmp_mpi -in in.lj
+
+Note that without the mpi4py specific lines from ``test.py``
+
+.. code-block::
+
+   from lammps import lammps
+   lmp = lammps()
+   lmp.file("in.lj")
+
+running the script with ``mpirun`` on :math:`P` processors would lead to
+:math:`P` independent simulations to run parallel, each with a single
+processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS
+single processor outputs, mpi4py is not working correctly.
+
+Also note that once you import the mpi4py module, mpi4py initializes MPI
+for you, and you can use MPI calls directly in your Python script, as
+described in the mpi4py documentation.  The last line of your Python
+script should be ``MPI.finalize()``, to insure MPI is shut down
+correctly.
+
+
+Running Python scripts
+----------------------
+
+Note that any Python script (not just for LAMMPS) can be invoked in
+one of several ways:
+
+.. code-block:: bash
+
+   $ python script.py
+   $ python -i script.py
+   $ ./script.py
+
+The last command requires that the first line of the script be
+something like this:
+
+.. code-block:: bash
+
+   #!/usr/bin/python
+   #!/usr/bin/python -i
+
+where the path points to where you have Python installed, and that you
+have made the script file executable:
+
+.. code-block:: bash
+
+   $ chmod +x script.py
+
+Without the ``-i`` flag, Python will exit when the script finishes.
+With the ``-i`` flag, you will be left in the Python interpreter when
+the script finishes, so you can type subsequent commands.  As
+mentioned above, you can only run Python interactively when running
+Python on a single processor, not in parallel.

doc/src/Python_run.rst

@@ -1,110 +1,23 @@
 Run LAMMPS from Python
 ======================
 
-Running LAMMPS and Python in serial:
+After compiling the LAMMPS shared library and making it ready to use,
--------------------------------------
+you can now write and run Python scripts that import the LAMMPS Python
+module and launch LAMMPS simulations through Python scripts.
+The following pages take you through the various steps necessary,
+what functionality is available and give some examples how to use it.
 
-To run a LAMMPS in serial, type these lines into Python
+------
-interactively from the ``bench`` directory:
 
-.. code-block:: python
+.. toctree::
+   :maxdepth: 1
 
-   >>> from lammps import lammps
+   Python_launch
-   >>> lmp = lammps()
+   Python_create
-   >>> lmp.file("in.lj")
+   Python_execute
-
+   Python_properties
-Or put the same lines in the file ``test.py`` and run it as
+   Python_atoms
-
+   Python_objects
-.. code-block:: bash
+   Python_scatter
-
+   Python_neighbor
-   $ python3 test.py
+   Python_config
-
-Either way, you should see the results of running the ``in.lj`` benchmark
-on a single processor appear on the screen, the same as if you had
-typed something like:
-
-.. code-block:: bash
-
-   lmp_serial -in in.lj
-
-Running LAMMPS and Python in parallel with MPI
-----------------------------------------------
-
-To run LAMMPS in parallel, assuming you have installed the
-`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
-:ref:`python_install_mpi4py`, create a ``test.py`` file containing these lines:
-
-.. code-block:: python
-
-   from mpi4py import MPI
-   from lammps import lammps
-   lmp = lammps()
-   lmp.file("in.lj")
-   me = MPI.COMM_WORLD.Get_rank()
-   nprocs = MPI.COMM_WORLD.Get_size()
-   print("Proc %d out of %d procs has" % (me,nprocs),lmp)
-   MPI.Finalize()
-
-You can run the script in parallel as:
-
-.. code-block:: bash
-
-   $ mpirun -np 4 python3 test.py
-
-and you should see the same output as if you had typed
-
-.. code-block:: bash
-
-   $ mpirun -np 4 lmp_mpi -in in.lj
-
-Note that without the mpi4py specific lines from ``test.py``
-
-.. code-block::
-
-   from lammps import lammps
-   lmp = lammps()
-   lmp.file("in.lj")
-
-running the script with ``mpirun`` on :math:`P` processors would lead to
-:math:`P` independent simulations to run parallel, each with a single
-processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS
-single processor outputs, mpi4py is not working correctly.
-
-Also note that once you import the mpi4py module, mpi4py initializes MPI
-for you, and you can use MPI calls directly in your Python script, as
-described in the mpi4py documentation.  The last line of your Python
-script should be ``MPI.finalize()``, to insure MPI is shut down
-correctly.
-
-Running Python scripts
-----------------------
-
-Note that any Python script (not just for LAMMPS) can be invoked in
-one of several ways:
-
-.. code-block:: bash
-
-   $ python script.py
-   $ python -i script.py
-   $ ./script.py
-
-The last command requires that the first line of the script be
-something like this:
-
-.. code-block:: bash
-
-   #!/usr/bin/python
-   #!/usr/bin/python -i
-
-where the path points to where you have Python installed, and that you
-have made the script file executable:
-
-.. code-block:: bash
-
-   $ chmod +x script.py
-
-Without the ``-i`` flag, Python will exit when the script finishes.
-With the ``-i`` flag, you will be left in the Python interpreter when
-the script finishes, so you can type subsequent commands.  As
-mentioned above, you can only run Python interactively when running
-Python on a single processor, not in parallel.