Updated documentation HTML

docs/_sources/examples.rst.txt

@@ -11,7 +11,7 @@ Initializing the tool for the available MPI library::
 
 Launch a MPI command in a container::
 
- e4s-cl launch --image ./image.sif --backend singularity -- mpirun ./binary
+ e4s-cl launch --image ./image.sif --backend singularity mpirun ./binary
 
 Listing the available profiles::
 
@@ -26,18 +26,20 @@ Some MPI libraries behave differently according to the user's input, making them
 
 The following message will appear when a redundant execution is detected:
 
-.. code-block:: bash
+.. highlight:: bash
+.. code::
 
  $ e4s-cl init
- The target launcher /usr/bin/mpirun uses a single host by default, which may
- tamper with the library discovery. Consider running `e4s-cl profile detect`
- using mpirun specifying multiple hosts.
+ The target launcher /usr/bin/mpirun uses a single host by default, which
+ may tamper with the library discovery. Consider running `e4s-cl profile
+ detect` using mpirun specifying multiple hosts.
 
 To ensure the validity of the generated profile, a launcher command should be given with at least some communication between hosts. To do so, one can compile and then run a sample program using **e4s-cl**. Using a generic MPI library:
 
-.. code-block:: bash
+.. code::
 
- $ mpicc program.c -o example
- $ e4s-cl profile detect -p <profile_name> mpirun -hosts <host1>,<host2> ./example
+ $ mpicc program.c -o example
+ $ e4s-cl profile detect -p <profile_name> \
+ mpirun -hosts <host1>,<host2> ./example
 
 On success, the newly-created profile will be found in the profile list.

docs/_sources/installation.rst.txt

@@ -55,4 +55,4 @@ All of the above steps can be done at once by using :code:`make all`.
 
 .. code-block:: bash
 
- $ make INSTALLDIR=<prefix> man
+ $ make INSTALLDIR=<prefix>

docs/_sources/quickstart.rst.txt

@@ -1,26 +1,36 @@
 Quickstart
 -------------
 
-The CLI tool is called **e4s-cl**. It behaves as a supplementary launcher over regular MPI commands, but can also manage :ref:`profiles<profile>` containing information about a MPI library's dependencies.
+The CLI tool is called **e4s-cl**. It behaves as a supplementary launcher over \
+regular MPI commands, but can also manage :ref:`profiles<profile>` containing \
+information about a MPI library's dependencies.
 
-To begin using **e4s-cl**, the preferred method is to create a profile for the target library. This can be achieved by using the :ref:`init<init>` or :ref:`profile detect<profile_detect>` commands. The resulting profile can be inspected and modified using the :ref:`profile<profile>` sub-commands.
+To begin using **e4s-cl**, the preferred method is to create a profile for the \
+target library. The preferred method to achieve this is by using the \
+:ref:`init<init>` or :ref:`profile detect<profile_detect>` commands.
+The resulting profile can be inspected and modified using the \
+:ref:`profile<profile>` sub-commands.
 
+.. highlight:: bash
 .. code::
 
  $ e4s-cl init
  $ e4s-cl profile list
- == Profile Configurations (/home/user/.local/e4s_cl/user.json) =================
+ == Profile Configurations (/home/user/.local/e4s_cl/user.json) ==========
 
- +----------+-----------------------------+---------+-------+-----------+-------+
- | Selected |  Name  | Backend | Image | Libraries | Files |
- +==========+=============================+=========+=======+===========+=======+
- | * |  default | N/A | N/A | 6 | 7 |
- +----------+-----------------------------+---------+-------+-----------+-------+
+ +----------+----------------------+---------+-------+-----------+-------+
+ | Selected | Name | Backend | Image | Libraries | Files |
+ +==========+======================+=========+=======+===========+=======+
+ | * | default | N/A | N/A | 6 | 7 |
+ +----------+----------------------+---------+-------+-----------+-------+
  $ e4s-cl profile edit --backend singularity --image ./image.sif
 
 
-Once a profile has been created, it can be used to launch an MPI command ! The :ref:`profile select<profile_select>` command marks a profile as the default. Using the :ref:`launch<launch>` command, the program passed as an argument will be launched using the desired library.
+Once a profile has been created, it can be used to launch an MPI command !
+The :ref:`profile select<profile_select>` command marks a profile as the \
+default. Using the :ref:`launch<launch>` command, the program passed as an \
+argument will be launched using the desired library.
 
 .. code::
 
- $ e4s-cl launch mpirun -np 4 -hosts node1,node2 ./executable
+ e4s-cl launch mpirun -np 4 -hosts node1,node2 ./executable

docs/_sources/reference/init.rst.txt

@@ -15,21 +15,13 @@ Options
 
 To tailor the initialization process, values can be specified by the user:
 
---mpi path to a MPI installation to use instead of the system default
---source script to run before execution
---image identifier for the image to use when launching the container
---backend container technology to employ
+--mpi Path to a MPI installation to use instead of the system default
+--source Script to run before execution
+--image Identifier for the image to use when launching the container
+--backend Container technology to employ
+--profile Profile to create or overwrite
 
 Description
 -----------
 
-This command initializes E4S Container Launcher for the system's available MPI library.
-
-During initialization, the available MPI library is parsed and analyzed to guess its running requirements.
-A :ref:`profile<profile>` is created with the collected results from the analysis, and made accessible for the next :ref:`launch command<launch>`.
-
-.. caution::
-
- The process relies on the good configuration of the MPI launcher, but this may fail.
- A message will appear in case some limitations were detected.
- It is good practice to :ref:`perform this process manually<init_override>` to ensure the network stack is exposed to **e4s-cl**.
+.. automodule:: e4s_cl.cli.commands.init

docs/_sources/reference/launch.rst.txt

@@ -6,36 +6,77 @@
 Usage
 -----
 
+.. highlight:: bash
 .. code::
 
- e4s-cl launch [ OPTIONS ] [ -- ] < MPI Command >
+ e4s-cl launch [ OPTIONS ] [ MPI LAUNCHER [ -- ] ] < COMMAND >
 
 Options
 -------
 
 The `launch` command accepts several options to tune the outcome of its execution:
 
 --profile Profile to use for the execution
---image Identifier for the image to use when launching the container
+--image Path for the image to use when launching the container
 --backend Container technology to employ
 --libraries Comma-separated list of libraries to load at run-time
 --files Comma-separated list of files to make accessible in the container
 --source Path of script to source before execution
 
+.. admonition:: MPI launcher detection
+
+ E4S Container Launcher needs to determine the exact arguments of the \
+ launcher. Certain launchers may have unique options that **e4s-cl** \
+ may not recognize.
+
+ To ensure the arguments are understood correctly, an additional \
+ :kbd:`--` can be added between the launcher options and the command.
+
+ See the examples for an illustration.
+
 Description
 -----------
 
-E4S Container Launcher is a accessory launcher to ensure host MPI libraries are used in containers.
-It wraps around a valid MPI launch command to work.
+.. automodule:: e4s_cl.cli.commands.launch
+
+Examples
+---------
+
+A launch command using an explicit profile and an MPI launcher:
 
-The minimal options that must be given are:
+.. code::
+
+ e4s-cl launch --profile intel-21 mpirun -np 2 ./ping-pong
+
+A launch command using an explicit profile and an MPI launcher, but a different image than the profile's:
+
+.. code::
 
-* A container image;
-* A container technology to run the image with.
+ e4s-cl launch --profile intel-21 \
+ --image /home/user/ecp.simg \
+ mpirun -np 2 ./ping-pong
 
-When a :ref:`profile<profile>` is selected, options can be omitted as the profile's fields will be implicitly used.
-Command line options have precedence over profiles' fields.
+A launch command with implicit profile making explicit the launcher and launchee:
+
+.. code::
+
+ e4s-cl launch mpirun -np 2 -ppn 1 -- ./ping-pong
+
+A launch command importing binaries in the container before running a script without profile:
+
+.. code::
+
+ e4s-cl launch --files /bin/strace,/bin/lsof \
+ --backend singularity \
+ --image ~/Images/ecp.simg \
+ ./script.sh
+
+A launch command using a local :code:`mpich` library without profile:
+
+.. code::
 
-E4S Container Launcher will analyze the command line to determine the exact arguments of the launcher.
-Certain launchers have esoteric options that may prevent this system from working properly.
-To ensure the arguments are understood correctly, an additional :kbd:`--` can be added between the options and the MPI command.
+ e4s-cl profile launch --backend singularity \
+ --image /home/user/ecp.simg \
+ --libraries /home/user/spack/opt/spack/linux-arch-skylake_avx512/gcc-10.2.0/mpich-3.4.1-yjx3whq2g2mrzrws4xhoxyjt7hl6wvb5/lib/libmpi.so.12 \
+ --files /usr/share/hwdata/pci.ids \
+ mpirun -np 2 ./ping-pong

docs/_sources/reference/profiles/copy.rst.txt

@@ -11,5 +11,4 @@ Usage
 Description
 -------------
 
-Create a new profile as a copy of another existing one.
-The first argument is the name of the profile to copy, the second being the destination profile.
+.. automodule:: e4s_cl.cli.commands.profile.copy

docs/_sources/reference/profiles/create.rst.txt

@@ -1,3 +1,5 @@
+.. _profile_create:
+
 **create** - Create a new profile
 =================================
 
@@ -11,14 +13,13 @@ Usage
 Options 
 --------
 
---libraries A comma-separated of libraries to add to the profile
---files A comma-separated of files to add to the profile
+--libraries A space-separated list of libraries to add to the profile
+--files A space-separated list of files to add to the profile
 --image The image to use with the profile
 --backend The container technology to use for the profile's image
 --source Path towards a script to source before execution
 
 Description
 ------------
 
-Create a new profile with the name passed as the first argument.
-Arguments passed to options are directly added to the corresponding field of the newly-created profile.
+.. automodule:: e4s_cl.cli.commands.profile.create

docs/_sources/reference/profiles/delete.rst.txt

@@ -11,4 +11,4 @@ Usage
 Description
 -------------
 
-Delete a profile associated with the name passed as an argument.
+.. automodule:: e4s_cl.cli.commands.profile.delete

docs/_sources/reference/profiles/detect.rst.txt

@@ -18,17 +18,4 @@ Options
 Description
 ------------
 
-The **profile detect** command will create a profile from the analysis of a MPI binary's execution.
-This process uses system call interception to produce an exhaustive list of files required by the MPI process.
-
-.. warning::
- To get a complete dependency detection, it is best to follow those guidelines:
-
- * The MPI launcher and binary should use the host's MPI library, to be imported in the future containers;
- * The MPI program should call at least one collective to ensure the use of the network stack;
- * The process should be run on multiple nodes using the target network. Failure to do so may result in erroneous detection of communication libraries and thus may create communication errors when using the profile.
-
-Use :code:`-p/--profile` to select a output profile. If the option is not present, the selected profile will be overwritten instead.
-
-.. warning::
- Not specifying a profile will overwrite the selected profile on success !
+.. automodule:: e4s_cl.cli.commands.profile.detect

docs/_sources/reference/profiles/diff.rst.txt

@@ -0,0 +1,14 @@
+**diff** - Compare profiles
+=================================
+
+Usage
+------
+
+.. code::
+
+ e4s-cl profile diff <NAME> <OTHER NAME>
+
+Description
+-------------
+
+.. automodule:: e4s_cl.cli.commands.profile.diff

docs/_sources/reference/profiles/dump.rst.txt

@@ -11,5 +11,4 @@ Usage
 Description
 --------------
 
-Print profile in its internal representation (JSON format).
-Used to parse and/or access profiles in an script-accessible way.
+.. automodule:: e4s_cl.cli.commands.profile.dump

docs/_sources/reference/profiles/edit.rst.txt

@@ -11,22 +11,16 @@ Usage
 Options
 -----------
 
---new_name Change the profile's name
---backend Change the profile's backend
---image Change the profile's default image
---source Change the profile's default init script
---add-files Comma-separated list of files to add
---remove-files Comma-separated list of files to remove
---add-libraries Comma-separated list of libraries to add
---remove-libraries Comma-separated list of libraries to remove
+--new_name  Change the profile's name
+--backend  Change the profile's backend
+--image  Change the profile's default image
+--source  Change the profile's default init script
+--add-files  List of files to add
+--remove-files  List of files to remove
+--add-libraries  List of libraries to add
+--remove-libraries List of libraries to remove
 
 Description
 ------------
 
-Modify the profile associated to the name passed as an argument.
-
-Passing a value to the options **--new_name**, **--backend**, **--image**, **--source** will overwrite the profile's corresponding field.
-
-Passing a value to **--add-files**, **--remove-files**, **--add-libraries**, **--remove-libraries** will add or remove elements from the list of files or libraries, accordingly.
-
-The name argument can be omitted in case a profile is selected, in which case the selected profile is modified.
+.. automodule:: e4s_cl.cli.commands.profile.edit

docs/_sources/reference/profiles/index.rst.txt

@@ -13,50 +13,26 @@ Usage
  SUBCOMMAND := { create | copy | delete | edit | list | show
  | select | unselect | detect | dump }
 
+Description
+-----------
+
+.. automodule:: e4s_cl.cli.commands.profile
+
 Sub-Commands
 ------------
 
 .. toctree::
  :maxdepth: 1
 
- create
  copy
+ create
  delete
+ detect
+ diff
+ dump 
  edit
  list
- show
  select
+ show
  unselect
- detect
- dump 
-
-Description
------------
 
-A profile is a recorded collection of fields relating to a specific MPI library.
-
-+-------------+--------------------------------------------------------------+
-| Field | Description |
-+=============+==============================================================+
-| `name` | A name by which the profile is accessed and invoked |
-+-------------+--------------------------------------------------------------+
-| `image` | The path of a container image |
-+-------------+--------------------------------------------------------------+
-| `backend` | Identifier for a technology to launch the container with |
-+-------------+--------------------------------------------------------------+
-| `source` | Path of a script to source in the container before execution |
-+-------------+--------------------------------------------------------------+
-| `files` | List of files to make accessible to the running program |
-+-------------+--------------------------------------------------------------+
-| `libraries` | List of libraries to overload in the running program |
-+-------------+--------------------------------------------------------------+
-
-**e4s-cl** stores profiles to simplify :ref:`launch commands<launch>`.
-Profiles are accessed and edited using the `profile` sub-commands.
-
-Profile Selection
------------------
-
-A profile can be selected using the :ref:`profile select<profile_select>` command. The target profile is then implicitly used for most of the commands taking a profile as an argument.
-
-A unique profile can be selected at a time. Switching selection is done by selecting another profile. A selection can also be canceled by using :ref:`profile unselect<profile_unselect>`.

docs/_sources/reference/profiles/list.rst.txt

@@ -6,7 +6,7 @@ Usage
 
 .. code::
 
- e4s-cl profile list [ OPTIONS ]
+ e4s-cl profile list [ PATTERN ] [ OPTIONS ]
 
 Options
 ----------
@@ -16,5 +16,4 @@ Options
 Description
 ------------
 
-Print a list of all recorded profiles, along with a brief description.
-Pass option **-s** to print only the names and disable formatting.
+.. automodule:: e4s_cl.cli.commands.profile.list