Refactor dev guide

This should:
* provide a note that our counda env name has changed
* provide some guidance on which style of dev env (or not) to use
* provide some guidance on working in an IDE
* better explains how to use nox

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ### Changed
 
+- Refactored our development guide to clarify development environment setup and how to run tests
+  ([@jhkennedy](https://github.com/jhkennedy))
 - Use built-in `assert` statements instead of `unittest` assertions in
   integration tests ([#743](https://github.com/nsidc/earthaccess/issues/743))
   ([@chuckwondo](https://github.com/chuckwondo))

docs/contributing/development.md

@@ -11,61 +11,16 @@
 In order to develop new features or fix bugs etc. we need to set up a virtual
 environment and install the library locally.
 
-## Quickstart development
+## Development environment setup
 
-The fastest way to start with development is to use nox. If you don't have nox,
-you can use `pipx run nox` to run it without installing, or `pipx install nox`.
-If you don't have pipx (pip for applications), then you can install with
-`pip install pipx` (the only case were installing an application with regular
-pip is reasonable). If you use macOS, then pipx and nox are both in brew, use
-`brew install pipx nox`.
 
-To use, run `nox` without any arguments.  This will run the type check and unit
-test "sessions" (tasks) using your local (and active) Python version.
-Nox handles everything for you, including setting up a temporary virtual
-environment for each run.
+There are a few options for setting up a development environment; you can use Python's `venv`, use `conda`/`mamba`, or _not_
+manage one yourself and use `pipx` to run tests and build docs with `nox`.
 
-You can see all available sessions with `nox --list`:
-
-```
-$ nox --list
-Sessions defined in earthaccess/noxfile.py:
-
-* typecheck -> Typecheck with mypy.
-* tests -> Run the unit tests.
-- test-min-deps -> Run the unit tests using the lowest compatible version of all direct dependencies.
-- integration-tests -> Run the integration tests.
-- build-pkg -> Build a source distribution and binary distribution (wheel).
-- serve-docs -> Build the documentation and serve it.
-
-sessions marked with * are selected, sessions marked with - are skipped.
-```
-You can also run individual tasks (_sessions_ in `nox` parlance, hence the `-s`
-option below), like so:
-```bash
-nox -s integration-tests
-```
-and pass options to the underlying session like:
-```bash
-nox -s integration-tests -- [ARGS]
-```
-
-!!! tip
-
-    In order to run integration tests locally, you must set the
-    environment variables `EARTHDATA_USERNAME` and `EARTHDATA_PASSWORD` to your
-    username and password, respectively, of your
-    [NASA Earthdata](https://urs.earthdata.nasa.gov/) account (registration is
-    free).
-
-
-
-## Manual development environment setup
-
-While `nox` is the fastest way to get started, you will likely need a full
-development environment for making code contributions, for example to test in a
-REPL, or to resolve references in your favorite IDE.  This development
-environment also includes `nox`. You can create it with `venv`, `conda`, or `mamba`.
+* If you're a Windows user, you'll likely want to set up an environment yourself with `conda`/`mamba`.
+* If you're working in a JupyterHub, you'll likely want to set up an environment yourself with `conda`/`mamba`.
+* If you're using an IDE like VS Code or PyCharm, you'll likely want to set up an environment yourself with `venv` or `conda`/`mamba`.
+* If you're using a plain text editor and don't know how to or want to manage a virtual environment, you'll likely want to start with `pipx`.
 
 === "`venv`"
 
@@ -89,9 +44,11 @@ environment also includes `nox`. You can create it with `venv`, `conda`, or `mam
 
     `conda` and `mamba` are open-source package and environment managers that are language and platform agnostic.
     `mamba` is a newer and faster re-implementation of `conda` -- you can use either `conda` or `mamba`
-    in the commands below.
+    in the commands below. See the installation instructions here (we reccomend using Miniforge):
 
-    Create and activate the development environment with:
+    <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>.
+
+    Once you have `conda`/`mamba` installed, you can create and activate the development environment with:
 
     ```bash
     mamba env update -f environment.yml
@@ -101,6 +58,135 @@ environment also includes `nox`. You can create it with `venv`, `conda`, or `mam
     This will update (or create if missing) the `earthaccess` environment and active it. The `earthaccess` package will
     be installed into the environment in editable mode with the optional development dependencies.
 
+    !!! note
+
+        On Sept. 23, 2024, the name of the conda environment changed from `earthaccess-dev` to `earthacess` to align with
+        community best practices. If you have an `earthaccess-dev` environment, we reccomend deleting it and creating a new one.
+        From the repository root, you can do that with these commands:
+
+        ```bash
+        mamba env update -f environment.yml
+        mamba activate earthaccess
+        mamba env remove -n earthaccess-dev
+        ```
+
+=== "`pipx`+`nox`"
+
+    `pipx` is a tool to help you install and run end-user applications written in Python and `nox` is Python application
+    that automates testing in multiple Python environments. That means, we can let `pipx` and `nox` manage the `earthaccess`
+    development environment(s) entirely without having to set one up locally. See the `pipx` installation instructions here:
+    <https://github.com/pypa/pipx?tab=readme-ov-file#install-pipx>.
+
+    Once you have `pipx` installed, you can either run `nox` without installing it via:
+    ```bash
+    pipx run nox [NOX_ARGS]
+    ```
+    or intall `nox` into an isolated environment and run it with
+    ```bash
+    pipx install nox
+    nox [NOX_ARGS]
+    ```
+    `nox` handles everything for you, including setting up a temporary virtual environment for each test session.
+
+Now that you're development environment is set up, you can run the tests.
+
+## Running tests
+
+We recommend using `nox` to run the various test "sessions" (tasks) provided by `earthaccess`. To use, run `nox` without
+any arguments:
+```bash
+nox
+```
+
+This will run the type check and unit test "sessions" (tasks) using your local (and active) Python
+version. `nox` handles everything for you, including setting up a temporary virtual environment for each run.
+
+You can see all available sessions with `nox --list`:
+```
+$ nox --list
+Sessions defined in earthaccess/noxfile.py:
+
+* typecheck -> Typecheck with mypy.
+* tests -> Run the unit tests.
+- test-min-deps -> Run the unit tests using the lowest compatible version of all direct dependencies.
+- integration-tests -> Run the integration tests.
+- build-pkg -> Build a source distribution and binary distribution (wheel).
+- serve-docs -> Build the documentation and serve it.
+
+sessions marked with * are selected, sessions marked with - are skipped.
+```
+
+You can also run individual tasks (_sessions_ in `nox` parlance, hence the `-s` option below), like so:
+```bash
+nox -s integration-tests
+```
+and pass options to the underlying session like:
+```bash
+nox -s integration-tests -- [ARGS]
+```
+
+!!! info "Important"
+
+    In order to run integration tests locally, you must set the environment variables `EARTHDATA_USERNAME` and
+    `EARTHDATA_PASSWORD` to the username and password of your [NASA Earthdata](https://urs.earthdata.nasa.gov/)
+    account, respectively (registration is free).
+
+### IDE setup
+
+Integrated development environments (IDEs) like VS Code and PyCharm provide powerful refactoring, testing, and
+debugging integrations, but they typically don't understand "task runners" like `nox` and won't know how to launch
+debugging or testing sessions connected to the provided integrations.
+
+Fortunately, if you've set up a development environment you should be able to call the underlying testing tools
+(e.g., `mypy` and `pytest`) directly, or run them via your IDE integrations. To understand how `nox` is running the
+underlying tools in each test session you can read the `noxfile.py` in the repository root, or, run all the test directly
+in your development environment like:
+```bash
+nox -fb none --no-install
+```
+This will force `nox` to not use an environment backend (will just use the active environment) and not attempt to install
+any packages. When `nox` runs, it will describe the commands it executes:
+```
+$ nox -fb none --no-install
+nox > Running session typecheck
+nox > mypy
+Success: no issues found in 35 source files
+nox > Session typecheck was successful.
+nox > Running session tests
+nox > pytest tests/unit -rxXs
+========================================== test session starts ==========================================
+...
+==================================== 43 passed, 1 xfailed in 24.01s =====================================
+nox > Session tests was successful.
+nox > Ran multiple sessions:
+nox > * typecheck: success
+nox > * tests: success
+```
+Note these lines in particular:
+```
+nox > Running session typecheck
+nox > mypy
+nox > Running session tests
+nox > pytest tests/unit -rxXs
+```
+So to reproduce the typecheck session all you have to do is run `mypy` in your development environment. Similarly, reproducing
+the unit tests is running `pytest test/unit -rxXs`.
+
+Since we're not doing any complicated configuration or setting complicated arguments to pytest, simply hitting the "play" button
+for a pytest in your IDE should work once you've configured it to use your development environment.
+
+!!! info "Important"
+
+    Currently, our integration tests are *flakey* and a small number of random failures are expected. When the integration
+    test suite runs, it may retun a status code of 99 if the failure rate was less than an "acceptable" threshold. Since
+    any non-zero status code is considered an error, your console and/or IDE wll consider this a failure by default.
+    `nox`, however, knows about this special status code and will report a success. To get pytest or your IDE to match
+    this behavior, you can modify the special status code to be zero with the `EARTHACCESS_ALLOWABLE_FAILURE_STATUS_CODE`
+    evnironment variable:
+    ```bash
+    export EARTHACCESS_ALLOWABLE_FAILURE_STATUS_CODE=0
+    ```
+
 ## Managing Dependencies
 
 If you need to add a new dependency, edit `pyproject.toml` and insert the
@@ -130,14 +216,14 @@ Since `python-cmr` exposes the `cmr` package, the stubs appear under `stubs/cmr`
 To work on documentation locally, we provide a script that will automatically re-render the docs when you make changes:
 
 ```
-nox -s serve_docs
+nox -s serve-docs
 ```
 
 MkDocs does not support incremental rebuilds and will execute every Jupyter Notebook every time it builds a new
 version of the site, which can be quite slow. To speed up the build, you can pass MkDocs these options:
 
 ```
-nox -s serve_docs -- --dirty --no-strict
+nox -s serve-docs -- --dirty --no-strict
 ```
 
 !!! warning