Docs edits (#157)

* aekiss edits * bring back latest installation instructions * one-liner via conda * folders -> directories * update build docs instructions * #### -> ## * Usage: pip <command> [options] Commands: install Install packages. download Download packages. uninstall Uninstall packages. freeze Output installed packages in requirements format. inspect Inspect the python environment. list List installed packages. show Show information about installed packages. check Verify installed packages have compatible dependencies. config Manage local and global configuration. search Search PyPI for packages. cache Inspect and manage pip's wheel cache. index Inspect information available from package indexes. wheel Build wheels from your requirements. hash Compute hashes of package archives. completion A helper command used for command completion. debug Show information useful for debugging. help Show help for commands. General Options: -h, --help Show help. --debug Let unhandled exceptions propagate outside the main subroutine, instead of logging them to stderr. --isolated Run pip in an isolated mode, ignoring environment variables and user configuration. --require-virtualenv Allow pip to only run in a virtual environment; exit with an error otherwise. --python <python> Run pip with the specified Python interpreter. -v, --verbose Give more output. Option is additive, and can be used up to 3 times. -V, --version Show version and exit. -q, --quiet Give less output. Option is additive, and can be used up to 3 times (corresponding to WARNING, ERROR, and CRITICAL logging levels). --log <path> Path to a verbose appending log. --no-input Disable prompting for input. --proxy <proxy> Specify a proxy in the form scheme://[user:passwd@]proxy.server:port. --retries <retries> Maximum number of retries each connection should attempt (default 5 times). --timeout <sec> Set the socket timeout (default 15 seconds). --exists-action <action> Default action when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup, (a)bort. --trusted-host <hostname> Mark this host or host:port pair as trusted, even though it does not have valid or any HTTPS. --cert <path> Path to PEM-encoded CA certificate bundle. If provided, overrides the default. See 'SSL Certificate Verification' in pip documentation for more information. --client-cert <path> Path to SSL client certificate, a single file containing the private key and the certificate in PEM format. --cache-dir <dir> Store the cache data in <dir>. --no-cache-dir Disable the cache. --disable-pip-version-check Don't periodically check PyPI to determine whether a new version of pip is available for download. Implied with --no-index. --no-color Suppress colored output. --no-python-version-warning Silence deprecation warnings for upcoming unsupported Pythons. --use-feature <feature> Enable new functionality, that may be backward incompatible. --use-deprecated <feature> Enable deprecated functionality, that will be removed in the future. -> pip * slight rephrase on limitations * clarifications in contributors guide * fix typo Co-authored-by: Andrew Kiss <[email protected]> * fix typo Co-authored-by: Andrew Kiss <[email protected]> --------- Co-authored-by: Andrew Kiss <[email protected]>
COSIMA · Apr 22, 2024 · 986473e · 986473e
1 parent 2eebd2a
commit 986473e
Show file tree

Hide file tree

Showing 7 changed files with 73 additions and 65 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # regional-mom6
 
-*Python package for automatic generation of regional configurations for the [Modular Ocean Model 6](https://github.com/mom-ocean/MOM6).*
+*Python package for automatic generation of regional configurations for the [Modular Ocean Model version 6](https://github.com/mom-ocean/MOM6) (MOM6).*
 
 [![Repo status](https://www.repostatus.org/badges/latest/active.svg?style=flat-square)](https://www.repostatus.org/#active)
 [![conda forge](https://img.shields.io/conda/vn/conda-forge/regional-mom6.svg)](https://anaconda.org/conda-forge/regional-mom6)
@@ -27,10 +27,12 @@ The idea behind this package is that it should let the user sidestep some of the
 
 ## Limitations
 
-- Only supports one type of regional horizontal grid, namely one that's equally spaced in longitude
-  and latitude. Users can provide their own grid, or ideally [open a pull request](https://github.com/COSIMA/regional-mom6/pulls) with a method that implements another type of horizontal grid!
-- Only boundary segments that are parallel to either lines of constant longitude or constant latitude
-  lines are supported.
+- Only generates regional horizontal grids with uniform spacing in longitude and latitude.
+  However, users can provide their own non-uniform grid, or ideally
+  [open a pull request](https://github.com/COSIMA/regional-mom6/pulls) with a method that
+  generates other types of horizontal grids.
+- Only supports boundary segments that are parallel to either lines of constant longitude or
+  lines of constant latitude.
 
 
 ## We want to hear from you
@@ -64,11 +66,11 @@ conda install conda-forge::regional-mom6
 
 That's it -- now enjoy!
 
-#### "*But I want `pip`, can't I install with `pip`*?"
+#### "*But I want pip, can't I install with pip*?"
 
 To install via `pip` is a bit more cumbersome.
 
-A prerequisite is the binary `esmpy` dependency, which provides regridding capabilities.
+A prerequisite is the binary `esmpy` dependency, which provides re-gridding capabilities.
 The easiest way to install `esmpy` is via conda:
 
 ```bash
@@ -97,7 +99,7 @@ pip install git+https://github.com/COSIMA/regional-mom6.git
 ```
 
 to get the version that corresponds to the latest commit in GitHub.
-Alternatively, install the version that corresponds to a particular git commit using
+Alternatively, install the version that corresponds to a particular git commit using, for example,
 
 ```bash
 pip install git+https://github.com/COSIMA/regional-mom6.git@061b0ef80c7cbc04de0566df329c4ea472002f7e
@@ -122,7 +124,6 @@ necessarily those used by the GFDL's [`MOM6_examples`](https://github.com/NOAA-G
 
 The [example notebooks](https://regional-mom6.readthedocs.io/en/latest/demos.html) walk you through how to use
 the package using two different sets of input datasets.
-Please ensure that you can get at least one of these working on your setup with your MOM6 executable before trying modify the example to suit your domain with your bathymethry, forcing, and boundary conditions.
-
-You can download the notebooks [from Github](https://github.com/COSIMA/regional-mom6/tree/ncc/installation/demos) or by clicking on the download <img width="22" alt="download" src="https://github.com/COSIMA/regional-mom6/assets/7112768/2c1ae149-c6a8-4395-ab09-2f77588008d9"> button, e.g., at the top-right of the [regional tasmania forced by ERA5 example](https://regional-mom6.readthedocs.io/en/latest/demo_notebooks/reanalysis-forced.html).
+Please ensure that you can get at least one of these working on your setup with your MOM6 executable before trying to modify the example to suit your domain with your bathymetry, forcing, and boundary conditions.
 
+You can download the notebooks [from Github](https://github.com/COSIMA/regional-mom6/tree/main/demos) or by clicking on the download <img width="22" alt="download" src="https://github.com/COSIMA/regional-mom6/assets/7112768/2c1ae149-c6a8-4395-ab09-2f77588008d9"> button, e.g., at the top-right of the [regional Tasmania forced by ERA5 example](https://regional-mom6.readthedocs.io/en/latest/demo_notebooks/reanalysis-forced.html).
diff --git a/demos/premade_run_directories/README.md b/demos/premade_run_directories/README.md
@@ -0,0 +1,5 @@
+## Premade Run Directories
+
+These directories are used for the demo notebooks, and can be used as templates for setting up a new experiment. The [documentation](https://regional-mom6.readthedocs.io/en/latest/mom6-file-structure-primer.html) explains what all the files are for.
+
+The `common_files` folder contains all of the required files for a regional MOM6 run, including a `data_table` with constant surface forcing as a placeholder. The other two directories offer different choices for the surface forcing, affecting the `data_table`.
diff --git a/demos/premade_run_directories/readme_premade_rundirs.md b/demos/premade_run_directories/readme_premade_rundirs.md
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -10,20 +10,21 @@ how new docstrings or any new bits of documentation that you may have added look
 ## Testing
 
 To run the tests from a local clone of the repository we first need to create a conda
-environment with all the dependencies required. From the repositories local clone main
-directory do
+environment with all the required dependencies.
+
+We create the environment by calling
 
 ```{code-block} bash
 conda env create --prefix ./env --file environment-ci.yml
 ```
 
-and then activate it
+from the repository's local clone main directory. Then we activate it via
 
 ```{code-block} bash
 conda activate ./env
 ```
 
-Now we need to install the package in this environment as well as `pytest`
+We then install both the package in this environment as well as the `pytest` package:
 
 ```{code-block} bash
 python -m pip install .
@@ -36,8 +37,8 @@ Now we can run the tests with
 python -m pytest tests/
 ```
 
-If we also want to run the doctests (tests that appear as examples in various docstrings), we
-can use
+If we also want to run the doctests (that is, the tests that appear as examples in
+various docstrings), we can use
 
 ```{code-block} bash
 python -m pytest --doctest-modules tests/ regional_mom6/
@@ -46,30 +47,31 @@ python -m pytest --doctest-modules tests/ regional_mom6/
 ## Documentation
 
 To build the docs from a local clone of the repository we first need to create a conda
-environment. Navigate to the `docs` directory of your local repository clone (e.g., `cd docs`)
-and then 
+environment after we first navigate to the `docs` directory of our local repository clone.
 
 ```{code-block} bash
 cd docs
 conda create --name docs-env --file requirements.txt
 ```
 
-Then activate this environment and install the package itself as an editable install (`pip install -e`).
+We activate this environment and install the package itself as an editable install (`pip install -e`).
 
 ```{code-block} bash
 conda activate docs-env
 pip install -e ..
 ```
 
-Now we can make the docs
+Now we can build the docs via `make`:
 
 ```{code-block} bash
 make html
 ```
 
-and open `_build/html/index.html` in your favorite browser.
+and upon successful build, we preview the documentation by opening `_build/html/index.html`
+in our favorite browser.
 
-Alternatively, we can install the dependencies needed for the docs via `pip`; the rest is same, that is
+Alternatively, instead of creating a conda environment, we can install the required
+dependencies for the docs via `pip`; the rest is same, that is
 
 ```{code-block} bash
 cd docs

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,7 +1,7 @@
 Regional MOM6 Documentation
 ===========================
 
-*Python package for automatic generation of regional configurations for the `Modular Ocean Model 6`_.*
+Python package for automatic generation of regional configurations for the `Modular Ocean Model version 6`_ (MOM6).
 
 
 In brief...
@@ -35,11 +35,11 @@ Features
 Limitations
 ------------
 
-- Only supports one type of regional horizontal grid, namely one that's equally spaced in longitude
-  and latitude. Users can provide their own grid, or ideally `open a pull request`_ with a method
-  that implements another type of horizontal grid!
-- Only boundary segments that are parallel to either lines of constant longitude or constant latitude
-  lines are supported.
+- Only generates regional horizontal grids with uniform spacing in longitude and latitude.
+  However, users can provide their own non-uniform grid, or ideally `open a pull request`_
+  with a method that generates other types of horizontal grids.
+- Only supports boundary segments that are parallel to either lines of constant longitude or lines of
+  constant latitude.
 
 
 What you need to get started
@@ -50,12 +50,12 @@ What you need to get started
 3. a bathymetry file that at least covers your domain,
 4. 3D ocean forcing files *of any resolution* on your choice of A, B, or C Arakawa grid,
 5. surface forcing files (e.g., from ERA or JRA reanalysis), and
-6. `GFDL's FRE tools <https://github.com/NOAA-GFDL/FRE-NCtools>`_ be downloaded and compiled on the machine you are using.
+6. `GFDL's FRE tools <https://github.com/NOAA-GFDL/FRE-NCtools>`_ downloaded and compiled on the machine you are using.
 
 Browse through the `demos <demos.html>`_.
 
 
-.. _Modular Ocean Model 6: https://github.com/mom-ocean/MOM6
+.. _Modular Ocean Model version 6: https://github.com/mom-ocean/MOM6
 .. _open a pull request: https://github.com/COSIMA/regional-mom6/pulls
 
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -1,4 +1,5 @@
-# Installation
+Installation
+============
 
 We encourage creating a new or using an existing conda environment.
 
@@ -16,7 +17,7 @@ That's it -- now enjoy!
 
 To install via `pip` is a bit more cumbersome.
 
-A prerequisite is the binary `esmpy` dependency, which provides regridding capabilities.
+A prerequisite is the binary `esmpy` dependency, which provides re-gridding capabilities.
 The easiest way to install `esmpy` is via conda:
 
 ```bash
@@ -45,7 +46,7 @@ pip install git+https://github.com/COSIMA/regional-mom6.git
 ```
 
 to get the version that corresponds to the latest commit in GitHub.
-Alternatively, install the version that corresponds to a particular git commit using
+Alternatively, install the version that corresponds to a particular git commit using, for example,
 
 ```bash
 pip install git+https://github.com/COSIMA/regional-mom6.git@061b0ef80c7cbc04de0566df329c4ea472002f7e