Merge pull request #350 from cyndy-llnl/llnl-edits

Copyedits for grammar and standardization

Author: hategan

CONTRIBUTING.md

@@ -8,13 +8,13 @@ details how to contribute in a standardized and efficient manner.
 
 ## Git Workflow Summary
 
-- Ensure that you've opened an Issue on Github and consensus around the
-  solution has be reached.
+- Ensure that you've opened an Issue on GitHub and consensus around the
+  solution has been reached.
   - Minor changes (e.g., grammatical fixes) do not require an Issue first.
-- Make a new branch for each separable set of changes — ["one task, one
-  branch"](https://mail.python.org/pipermail/ipython-dev/2010-October/005632.html).
-- [Each commit should make one change](https://dev.to/ruanbrandao/how-to-make-good-git-commits-256k).
-  to aide reviewing and (in the worst case) simplify reverting it in the future.
+- Make a new branch for each separable set of changes—["one task, one
+  branch."](https://mail.python.org/pipermail/ipython-dev/2010-October/005632.html).
+- [Each commit should make one change](https://dev.to/ruanbrandao/how-to-make-good-git-commits-256k)
+  to aid reviewing and (in the worst case) simplify reverting it in the future.
   - A patch commit message should consist of a single short (less than 50
     character) sentence summarizing the change, optionally followed by a blank line
     and then a more thorough description.
@@ -25,16 +25,16 @@ details how to contribute in a standardized and efficient manner.
   - If you do find yourself merging from upstream, consider [Rebasing on
     upstream](https://matplotlib.org/stable/devel/gitwash/development_workflow.html#rebase-on-trunk).
 - Submit a Pull Request from your feature branch against upstream.
-  - Use the Draft PR feature on Github or title your PR with `WIP` if your PR is
+  - Use the Draft PR feature on GitHub or title your PR with `WIP` if your PR is
     not ready for a complete review immediately upon submission.
-- Ask on the [Exaworks slack](https://exaworks.slack.com) if you get stuck.
+- Ask on the [Exaworks Slack](https://exaworks.slack.com) if you get stuck.
 
 
 ## Pull Request (PR) Merging Process
 
 - PR reviews should be timely. Both reviewer and PR issuer should make a good
   attempt at resolving the conversation as quickly as possible.
-- PR reviews exist to check obvious things aren't missed, not to achieve
+- PR reviews exist to check that obvious things aren't missed, not to achieve
   perfection.
 - A PR is eligible for merging if it has at least one approval from a
   project maintainer, no outstanding requested changes or discussions, and passes
@@ -55,16 +55,16 @@ under-the-hood. PEP8 compliance is also verified as part of the CI by `flake8`.
 
 ## Type Annotations
 
-As much python code in this repo as is feasible should include type annotations.
+As much Python code in this repo as is feasible should include type annotations.
 These type annotations can then be ingested and checked by `mypy`, which can be
 run with `make typecheck` and `make checks`.
 
 ## Docstrings
 
-As many public python interfaces in this repo as is feasible should
+As many public Python interfaces in this repo as is feasible should
 include docstring documentation. All docstrings should follow the
 [numpy format](https://numpydoc.readthedocs.io/en/latest/format.html). These
 docstrings are automatically parsed by Sphinx and turned into html-based
 documentation hosted on readthedocs. Document generation can be run locally
 with `make docs`. For more details about building the documentation, please
-see [`README-dev`][README-dev.md].
+see [`README-dev`](README-dev.md).

QuickStart.md

@@ -1,4 +1,4 @@
-# Quick start guide
+# Quick Start Guide
 
 This document will guide you through the install procedure and your first hello world example.
 
@@ -17,9 +17,9 @@ If you have conda installed you might want to start from a fresh environment. Th
 2. `conda activate psij`
 
 
-Install psij from the github repository:
+Install psij from the GitHub repository:
 
-1. Clone repository into your working directory:
+1. Clone the repository into your working directory:
 
     `git clone https://github.com/ExaWorks/psij-python.git`
 
@@ -32,15 +32,15 @@ Install psij from the github repository:
 
 
 
-## Hello world
+## Hello World
 
 **Requirements**
 - python3.7
-- job executioner, e.g. slurm in this example
+- Job executor, e.g. Slurm in this example
 
 **Steps**
 
-1. Create a file *my-workflow.py* and copy and paste the code below:
+1. Create a file *my-workflow.py* and copy and paste this code:
 
 ```python
 
@@ -82,7 +82,6 @@ for i in range(N):
     jobs[i].wait()
 
 ```
-2. In this example the number of jobs is 1. Set *N* to the number of jobs you want to run and save file.
+2. In this example the number of jobs is 1. Set *N* to the number of jobs you want to run and save the file.
 
 3. `python my-workflow.py`
-

README-dev.md

@@ -4,7 +4,7 @@
 
 There are two ways to build the documentation. One is the plain one, where
 the plain Sphinx output is desired, and the other is the themed version that
-is meant to integrate with the web site.
+is meant to integrate with the website.
 
 !!! Note
 
@@ -30,15 +30,15 @@ The output will be in `docs/.build`
 
 ### Building the Themed Documentation
 
-This builds the themed version of the docs as well as the web site. The steps
+This builds the themed version of the docs as well as the website. The steps
 are:
 
 1. Make sure you have the dependencies installed:
     ```sh
     pip install -r requirements-docs.txt
     ```
 
-2. Build the web site, which builds the themed version of the documentation
+2. Build the website, which builds the themed version of the documentation
 automatically:
     ```
     web/build.sh
@@ -62,16 +62,17 @@ which will output something like this:
   Server running... press ctrl-c to stop.
 ```
 
+
 Pointing your web browser to the URL printed by Jekyll will show the PSI/J
 web site. The themed documentation will be found under the "Documentation"
 tab.
 
 
-### Release process
+### Release Process
 
 Here are the steps for putting out a fresh release to Pypi.
 
-1. Create a new branch from main, and make release specific updates:
+1. Create a new branch from main and make release specific updates:
     * Update `src/psij/version.py` to the new version number
 
 2. Use the standard PR process and get changes from the above step merged to main.
@@ -80,6 +81,6 @@ Here are the steps for putting out a fresh release to Pypi.
    setup tokens on your machine.
 
 4. Run `make VERSION="version string" tag-and-release`. This will:
-    1. Create and push tags to github
-    2. Build the package
-    3. Push built package to Pypi.
+    * Create and push tags to GitHub.
+    * Build the package.
+    * Push built package to Pypi.

README-testing.md

@@ -10,16 +10,16 @@ are uploaded to a test aggregation service. The compatibility of various
 PSI/J branches with various resources can then be assessed and is
 available at https://testing.exaworks.org
 
-How to run tests
+How to Run Tests
 ================
 
 There are a number of ways to run tests. Invoking `pytest` directly,
-running the integration tests and through `cron` (or a similar tool).
+running the integration tests, and through `cron` (or a similar tool).
 
-Setting up an automated testing job
+Setting up an Automated Testing Job
 ===================================
 
-This is the preferred way of running the tests since it allows the PSI/J
+This is the preferred way of running tests since it allows the PSI/J
 team to keep a constant eye on the state of the library on various
 resources. To set up the Cron job (or an alternative method), you can either
 use the provided setup script:
@@ -37,7 +37,7 @@ virtual environment, please run the relevant commands before invoking
 `psij-ci-setup`.
 
 
-Testing with the CI runner
+Testing with the CI Runner
 ==========================
 
 The CI runner is a convenience script which can clone the PSI/J
@@ -106,4 +106,3 @@ or, using `make`, prefix all options with a double dash ("--"):
 Care must, however, be taken since it is impossible to preserve
 whitespace and certain special characters (such as the double quotes)
 when passing arguments through `make`.
-

README.md

@@ -14,8 +14,8 @@ documentation](https://exaworks.org/psij-python/#docs).
 
 ## Introduction
 
-1. [Quick start guide](QuickStart.md)
-2. [Workflow examples](scripts/WORKFLOW-EXAMPLES.md)
-3. [Setting up tests](README-testing.md)
-4. [How to contribute](CONTRIBUTING.md)
-5. [Building the documentation](README-dev.md)
+1. [Quick Start Guide](QuickStart.md)
+2. [Workflow Examples](scripts/WORKFLOW-EXAMPLES.md)
+3. [Setting up Tests](README-testing.md)
+4. [How to Contribute](CONTRIBUTING.md)
+5. [Building the Documentation](README-dev.md)

docs/api.rst

@@ -4,13 +4,13 @@ The PSI/J API
 The most important classes in this library are ``Job`` and ``JobExecutor``,
 followed by ``Launcher``.
 
-The Job class and its modifiers
+The Job Class and Its Modifiers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Job-related classes listed in this section (``Job``, ``JobSpec``,
 ``ResourceSpec``, and ``JobAttributes``) are independent of
 executor implementations. The authors strongly recommend that users
-program against these classes, rather than adding executor-specific
+program against these classes rather than adding executor-specific
 configuration options, to the extent possible.
 
 .. autoclass:: psij.Job
@@ -25,15 +25,15 @@ configuration options, to the extent possible.
     :members:
     :noindex:
 
-Job modifiers
+Job Modifiers
 ^^^^^^^^^^^^^
 
 There can be a lot of configuration information that goes into each
 resource manager job. Its walltime, partition/queue, the number of nodes
 it needs, what kind of nodes, what quality of service the job requires, and
 so on.
 
-PSI/J splits those three attributes into three groups: one for generic
+PSI/J splits those attributes into three groups: one for generic
 POSIX information, one for resource information, and one for resource manager
 scheduling policies.
 
@@ -59,15 +59,15 @@ Executors are concrete implementations of mechanisms that execute jobs.
 To get an instance of a specific executor, call
 :meth:`JobExecutor.get_instance(name) <psij.job_executor.JobExecutor.get_instance>`,
 with ``name`` being one of the installed executor names. Alternatively, directly
-instantiate the executor, e.g.
+instantiate the executor, e.g.:
 
 .. code-block:: python
 
     from psij.executors.flux import FluxJobExecutor
 
     ex = FluxJobExecutor()
 
-Rather than
+Rather than:
 
 .. code-block:: python
 
@@ -152,15 +152,15 @@ are wrappers around the job executable which can provide additional
 features, such as setting up an MPI environment, starting a copy of the
 job executable on each allocated node, etc. To get a launcher instance,
 call :meth:`Launcher.get_instance(name) <psij.launcher.Launcher.get_instance>`
-with ``name`` being the name of a launcher. Like job executors, above,
+with ``name`` being the name of a launcher. Like job executors,
 launchers are plugins and can come from various places. To obtain a list
 of launchers, you can run:
 
 .. code-block:: shell
 
     $ python -m psij plugins
 
-Launcher base class
+Launcher Base Class
 ^^^^^^^^^^^^^^^^^^^
 
 Like the executor, the ``Launcher`` base class is abstract, but offers

docs/development/contributing.rst

@@ -12,8 +12,7 @@ to create issues and pull requests. Please follow the
 `contributing guide <https://github.com/ExaWorks/psij-python/blob/main/CONTRIBUTING.md>`_.
 
 Please note that many high-level design questions may be better discussed in
-the `PSI/J design repo <https://github.com/ExaWorks/job-api-spec>`_, rather than the Python library implementation
-linked to above.
+the `PSI/J design repo <https://github.com/ExaWorks/job-api-spec>`_, rather than the Python library implementation.
 
 Feel free to chat with the developers on our `Slack <https://exaworks.slack.com>`_!
 
@@ -26,7 +25,7 @@ Once you have cloned the code and installed the dependencies
 suite with ``make tests``. To run the style and type checks, run
 ``make checks``.
 
-The testing dashboard website
+The Testing Dashboard Website
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To record your test results to PSI/J's public testing dashboard,

docs/development/programming.rst

@@ -92,7 +92,7 @@ This is an abstract base class for submit-script based executors. It assumes
 a Local Resource Manager (LRM) that allows job submission by pointing a
 *submit* command (a tool accessible through a standard POSIX `exec()`) to a
 file that contains all relevant job information. It also assumes that there
-exist commands for cancelling the job, and for querying for the status of one
+exist commands for cancelling the job and for querying for the status of one
 or more jobs previously submitted.
 
 The general workflow used by the batch scheduler executor to submit a job is as
@@ -151,7 +151,7 @@ standard streams of the actual launcher tool, which is assumed to properly
 aggregate the output streams of the job ranks.
 
 In addition to the functions above, PSI/J launchers also take care of invoking
-the pre and post launch scripts.
+the pre- and post-launch scripts.
 
 Since script based launchers are interchangeable, they must have a well
 defined interface. This interface consists of:
@@ -175,5 +175,5 @@ defined interface. This interface consists of:
 Writing a custom script based launcher can be as easy as subclassing
 :class:`~psij.launchers.script_based_launcher.ScriptBasedLauncher` and passing
 a launcher script path to the base class constructor. For example, see the
-`MPI launcher class <https://github.com/ExaWorks/psij-python/blob/main/src/psij/launchers/mpirun.py>` and the
-`MPI launcher script <https://github.com/ExaWorks/psij-python/blob/main/src/psij/launchers/scripts/mpi_launch.sh>`.
+`MPI launcher class <https://github.com/ExaWorks/psij-python/blob/main/src/psij/launchers/mpirun.py>`_ and the
+`MPI launcher script <https://github.com/ExaWorks/psij-python/blob/main/src/psij/launchers/scripts/mpi_launch.sh>`_.