Improve contribution instructions and clean up readme

.gitignore

@@ -21,3 +21,23 @@ _build.*
 pynucastro/_version.py
 
 /docs/build/
+
+# Distribution / packaging (from github/gitignore)
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST

CONTRIBUTING.md

@@ -18,29 +18,71 @@ reproduce the bug including your version of python.
 ## Pull Requests
 
 *Any contributions that have the potential to change answers should be
-done via pull requests.* A pull request should be generated from your
-fork of pynucastro and target the `main` branch.
+done via pull requests.* A pull request should be generated from a
+feature branch in your fork of pynucastro and target the `main` branch.
 
-You should run the `pytest` unit tests on your changes, if possible,
-before issuing the PR. To run the unit tests, in the repository root
-run:
+You should run the test suite on your changes, if possible, before
+issuing the PR. See the section below for detailed instructions.
 
-```
-pytest -v
-```
-
-To regenerate the reference network output files used in the unit
-tests, run:
-
-```
-pytest -v -s --update-networks -k write_network
-```
-
-Once you have run the unit tests and submitted the PR, one of the
+Once you have run the tests and submitted the PR, one of the
 pynucastro developers will review the PR and if needed, suggest
 modifications prior to merging the PR.
 
 If there are a number of small commits making up the PR, we may wish
 to squash commits upon merge to have a clean history.  *Please ensure
 that your PR title and first post are descriptive, since these will be
 used for a squashed commit message.*
+
+## Testing
+
+We use pytest to do unit and regression tests. All commands should be
+run from the repository root.
+
+* To run all the tests:
+
+  ```
+  pytest -v --nbval
+  ```
+
+* To run just the unit tests (this is faster, but may not catch all bugs):
+
+  ```
+  pytest -v
+  ```
+
+* To run just the jupyter notebook regression tests:
+
+  ```
+  pytest -v --nbval -p no:python
+  ```
+
+  This executes each of the notebooks under `examples/` and `docs/source/`
+  and compares against the stored outputs from each cell.
+
+* To check code coverage:
+
+  ```
+  pytest --cov=pynucastro --nbval
+  ```
+
+  The results can be inspected in more detail by running `coverage html`
+  and opening the generated `htmlcov/index.html` in a web browser.
+
+  Note that numba-accelerated routines (most notably the screening
+  functions) do not support coverage reporting, and will always show up
+  as missed.
+
+* To regenerate the reference network output files used in the unit tests:
+
+  ```
+  pytest -v -s --update-networks -k write_network
+  ```
+
+  This will be needed if any of the network generation code or C++
+  network templates are changed.
+
+* To re-run notebooks whose outputs have changed:
+
+  ```
+  docs/regen_notebook.sh <path to notebook>
+  ```

README.md

@@ -17,7 +17,7 @@
 pynucastro is a python library for interactively creating and
 exploring nuclear reaction networks.  It provides interfaces to
 nuclear reaction rate databases, including the JINA Reaclib nuclear
-reactions database.  
+reactions database.
 
 The main features are:
 
@@ -41,14 +41,14 @@ The main features are:
     functions, spins, masses, etc.
 
 
-# documentation
+## Documentation
 
 Documentation for pynucastro is available here:
 
-http://pynucastro.github.io/pynucastro/
+https://pynucastro.github.io/pynucastro/
 
 
-# example
+## Examples
 
 The following example reads in the ReacLib rate database and
 gets the rate for C13(p,g)N14 and evaluates it at a
@@ -90,7 +90,7 @@ then the breakout of hot-CNO when the alpha capture on O14 becomes
 faster than its decay.
 
 
-# install
+## Installation
 
 pynucastro is available on PyPI and can be installed via:
 ```
@@ -109,7 +109,7 @@ for a single-user install.  This will put the pynucastro modules and library in
 the default location python searches for packages.
 
 
-# requirements
+### Requirements
 
 This package requires Python 3 (release 3.6 or later) and the following Python packages:
 
@@ -127,8 +127,6 @@ This package requires Python 3 (release 3.6 or later) and the following Python p
 
 * `numba`
 
-* `setuptools_scm`
-
 To build the documentation or run the unit tests, `sphinx` and
 `pytest` are additionally required along with some supporting
 packages. See the included `requirements.txt` file for a list of these
@@ -141,25 +139,18 @@ Is important to stress out that all the dependencies should be
 installed before `pynucastro`, otherwise the installation should be 
 repeated.
 
-# unit tests
 
-We use pytest to do unit tests.  In the repository root, do:
-```
-pytest -v
-```
+## Contributing
 
-to see coverage, do:
-```
-pytest --cov=pynucastro
-```
+We welcome contributions from anyone, including posting issues or
+submitting pull requests to the [pynucastro github][1]. For more details
+on how to contribute to pynucastro, please see [CONTRIBUTING.md][2].
 
-to test the notebooks, do:
-```
-pytest --nbval examples
-```
+[1]: https://github.com/pynucastro/pynucastro
+[2]: https://github.com/pynucastro/pynucastro/blob/main/CONTRIBUTING.md
 
 
-# Core Developers
+### Core Developers
 
 People who make a number of substantive contributions (new features,
 bug fixes, etc.) will be named "core developers" of pynucastro.
@@ -180,3 +171,10 @@ Core developers will be recognized in the following ways:
 If a core developer is inactive for 3 years, we may reassess their
 status as a core developer.
 
+
+## Getting Help
+
+We use our [Github Discussions][3] page for requesting help and
+interacting with the community.
+
+[3]: https://github.com/pynucastro/pynucastro/discussions

docs/source/contributing.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../CONTRIBUTING.md

docs/source/index.rst

@@ -22,6 +22,7 @@ codes.
    intro
    rate_types
    install
+   contributing
 
 .. toctree::
    :maxdepth: 1