Apply suggestions from code review

Author: hategan

docs/api.rst

@@ -5,7 +5,7 @@ The most important classes in this library are ``Job`` and ``JobExecutor``,
 followed by ``Launcher``.
 
 The Job Class and Its Modifiers
-----------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Job-related classes listed in this section (``Job``, ``JobSpec``,
 ``ResourceSpec``, and ``JobAttributes``) are independent of
@@ -26,7 +26,7 @@ configuration options.
     :noindex:
 
 Job Modifiers
-----------------
+^^^^^^^^^^^^^
 
 There can be a lot of configuration information that goes into each
 resource manager job, including its walltime, partition/queue, the number of nodes
@@ -53,7 +53,7 @@ scheduling policies.
 .. _executors:
 
 Executors
-----------------
+~~~~~~~~~
 
 Executors are concrete implementations of mechanisms that execute jobs.
 To get an instance of a specific executor, call

docs/development/tutorial_add_executor.rst

@@ -27,7 +27,7 @@ For example, with PBS `qsub` and `qstat` commands are used to submit a request a
 To use BatchSchedulerExecutor for a new local resource manager that uses this command line interface, subclass BatchSchedulerExecutor and add in code that understands how to form the command lines necessary to submit a request for an allocation and to get allocation status. This tutorial will do that for PBSPro.
 
 Adding an Executor
-----------------
+------------------
 
 First set up a directory structure::
 
@@ -53,7 +53,7 @@ Prerequisites:
 First, we'll build a skeleton that won't work, and see that it doesn't work in the test suite. Then we'll build up to the full functionality.
 
 A Not-implemented Stub
-^^^^^^^^^^^^^^
+----------------------
 
 Add the project directory to the Python path directory::
 

docs/getting_started.rst

@@ -83,7 +83,7 @@ Local // Slurm // LSF // PBS // Cobalt
     job = Job(JobSpec(executable="/bin/date"))
     ex.submit(job)
 
-The ``executable="/bin/date")`` tells PSI/J that we want the job to run
+The ``executable="/bin/date"`` parameter tells PSI/J that we want the job to run
 the ``/bin/date`` command. Once that command has finished executing
 (which should be almost as soon as the job starts, since ``date`` does very little work)
 the resource manager will mark the job as complete, triggering PSI/J to do the same.

docs/index.rst

@@ -16,16 +16,16 @@ scheduler. PSI/J has a number of advantages:
 
 #. **Offers an asynchronous modern API for job management.** PSI/J is a clean Python API for requesting and managing jobs that works across a variety of HPC centers.
 
-#. **Supports common batch schedulers.** It's easy to test PSI/J on your systems—including multiple DOE supercomputer centers—and share the results with the community.
+#. **Supports the common batch schedulers:** We test PSI/J across multiple DOE supercomputer centers. It's easy to test PSI/J on your systems and share the results with the community.
 
 #. **Is built by the HPC community, for the HPC community:** PSI/J is based on a number of libraries used by state-of-the-art HPC workflow applications.
 
-#. **Leverages contributor expertise as an open source project:** We are establishing a community to develop, test, and deploy PSI/J across many HPC facilities.
+#. **PSI/J is an open source project:** We are establishing a community to develop, test, and deploy PSI/J across many HPC facilities.
 
 Most HPC centers feature multiple schedulers, rolling policy changes and
 deployments of software stacks, and subtle differences even across systems with
-similar architectures. **PSI/J tames this complexity** for
-computational scientists and workflow developers.
+similar architectures. **PSI/J is designed to tame this complexity** and provide
+computational scientists and workflow developers a common API for interacting
 
 
 

docs/user_guide.rst

@@ -14,7 +14,7 @@ PSI/J simplifies your work.
 
 
 When Not to Use PSI/J
-^^^^^^^^^^^^^^
+-------------------------------
 
 If you are certain that you will only *ever* be launching jobs on ORNL's Summit
 system and you don't care about any other cluster or machine, it makes sense to 
@@ -53,7 +53,7 @@ What is a JobExecutor?
 
 A :class:`JobExecutor <psij.job_executor.JobExecutor>` represents a specific RM,
 e.g. Slurm, on which the job is being executed.  Generally, when jobs are
-submitted they will be queued depending on how
+submitted they will be queued for a variable period of time, depending on how
 busy the target machine is. Once the job is started, its executable is
 launched and runs to completion, and the job will be marked as completed.
 
@@ -81,7 +81,7 @@ reference the `developer documentation
 
 
 Submitting a Job
-------------
+----------------
 
 The most basic way to use PSI/J looks something like the following:
 
@@ -112,7 +112,7 @@ manager’s queue after running the example above.
 
 
 Submitting Multiple Jobs
-^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 In the last section we submitted a single job.  Submitting multiple jobs is as
 simple as adding a loop:
@@ -133,7 +133,7 @@ numbers of jobs (tested with up to 64k jobs).
 Configuring Your Job
 --------------------
 
-In the example above, the ``executable='/bin/date'`` tells PSI/J that we want
+In the example above, ``executable='/bin/date'`` tells PSI/J that we want
 the job to run the ``/bin/date`` command. But there are other parts of the job
 which can be configured:
 

web/about.html

@@ -16,9 +16,9 @@ <h2>The motivation behind <span class="psij-font">PSI/J</span></h2>
                                     Project</a> which brings together a number of high level HPC tools developed
                                 by the members of ExaWorks. We noticed that most of these projects, as well as
                                 many of the community projects, implemented a software layer/library to interact
-                                with HPC schedulers in order to insulate the core functionality from the detailed
-                                scheduler specifications. We also noticed that
-                                the respective libraries were limited to schedulers running on resources that
+                                with HPC schedulers in order to insulate the core functionality from the
+                                details of how things are specified for each scheduler. We also noticed that
+                                the respective libraries were mostly limited to schedulers running on resources that
                                 each team had access to. We used our combined knowledge to
                                 design a single API/library for this goal, one that would be tested on all
                                 resources that all ExaWorks teams have access to. We then shared this API

web/index.html

@@ -33,11 +33,11 @@
                                         <i class="fas fa-server" style="color: #9A4A68"></i>
                                     </div>
                                     <v-card-title class="text-h5 justify-center">
-                                        Run your HPC application anywhere 
+                                        Write Scheduler Agnostic HPC Applications 
                                     </v-card-title>
 
                                     <v-card-text>
-                                      <span class="psij-font>PSI/J</span>’s unified API automatically translates abstract job specs into concrete scripts and commands to send to the scheduler.
+                                      Use a unified API to enable your HPC application to run virtually anywhere.
                                     </v-card-text>
                                 </v-card>
                             </v-col>
@@ -52,29 +52,29 @@
                             <v-col justify="center">
                                 <v-card align="center">
                                     <div class="icon-logo"><i class="fas fa-terminal" style="color: #DD3D5A"></i></div>
-                                    <h3>Stay on top of cluster changes </h3>
+                                    <h3><span class="psij-font">PSI/J</span> runs entirely in user space</h3>
 
                                     <v-card-text>
-                                        Quickly respond to experimental changes in the cluster environment rather than waiting for infrequent deployment cycles. 
+                                        here is no need to wait for infrequent deployment cycles. The HPC world
                                     </v-card-text>
                                 </v-card>
                             </v-col>
                             <v-col justify="center">
                                 <v-card align="center">
                                     <div class="icon-logo"><i class="fas fa-puzzle-piece" style="color: #F15A3D"></i>
                                     </div>
-                                    <h3>Leverage a community of coders</h3>
+                                    <h3>Use built-in or community contributed plugins</h3>
 
                                     <v-card-text>
-                                        Community contributors expand its utility across a variety of clusters with constant extensions and improvements. 
+                                        It is virtually impossible for a single entity to
                                     </v-card-text>
                                 </v-card>
                             </v-col>
 
                             <v-col justify="center">
                                 <v-card align="center">
                                     <div class="icon-logo"><i class="fas fa-save" style="color: #FDA214"></i></div>
-                                    <h3>Rely on a state-of-the-art HPC workflow </h3>
+                                    <h3><span class="psij-font">PSI/J</span> has a rich HPC legacy</h3>
 
                                     <v-card-text>
                                         <span class="psij-font">PSI/J</span> was built by a team with decades of experience building workflow systems for large scale computing.