Merge pull request #5 from AlanPearl/2-contributing

Contributing guidelines
AlanPearl · Nov 26, 2024 · 09a760d · 09a760d
2 parents 43d4b57 + 805c0fa
commit 09a760d
Show file tree

Hide file tree

Showing 6 changed files with 42 additions and 3 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# Contributing to `diffopt`
+
+Thank you for your interest in contributing to this project. All questions and ideas for improvement are welcome and can be made through opening an issue or pull request.
+
+Before contributing, familiarize yourself with our resources:
+
+- [Source Code](https://github.com/AlanPearl/diffopt)
+- [Documentation](https://diffopt.readthedocs.io)
+
+## Issues
+
+You can open an [issue](https://github.com/AlanPearl/diffopt/issues) if you:
+
+- Have encountered a bug or issue when using the software
+- Would like to see a new feature
+- Are seeking support that could not be resolved by reading the documentation
+
+## Pull Requests
+
+If you would like to directly submit your own change to the software, thank you! Here's how:
+
+- Fork [this repository](https://github.com/AlanPearl/diffopt).
+- Please remember to include a concise, self-contained unit test in your pull request. Ensure that all tests pass (see [Manual Testing](#manual-testing)).
+- Open a [pull request](https://github.com/AlanPearl/diffopt/pulls).
+
+## Manual Testing
+
+Make sure you have installed diffopt as described in the [docs](https://diffopt.readthedocs.io/en/latest/installation.html). To run all tests from the main directory:
+
+```bash
+pip install pytest
+pytest .
+mpirun -n 2 pytest .
+```
+
+Note that unit tests requiring `mpi4py` installation are not automatically tested by GitHub workflows. Therefore, running these tests manually with `mpi4py` installed is necessary to assure that all tests pass.
diff --git a/README.md b/README.md
@@ -6,6 +6,3 @@ Parallelization and optimization of differentiable and many-parameter models
 
 ## Documentation
 Online documentation is available at [diffopt.readthedocs.io](https://diffopt.readthedocs.io/en/latest).
-
-## Manual Testing
-Unit tests requiring `mpi4py` installation are not automatically tested by GitHub workflows. To run all tests, install `mpi4py` locally, and run `pytest` from the root directory. Additionally, all tests must pass with `mpirun -n 4 pytest` etc. (up to the maximum number of tasks that can be run on your machine).
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,6 @@
 sphinx_rtd_theme
 nbsphinx
+myst_parser
 IPython
 matplotlib
 seaborn

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -25,6 +25,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "nbsphinx",
+    "myst_parser",
 ]
 
 templates_path = ['_templates']

diff --git a/docs/source/include_contributing.rst b/docs/source/include_contributing.rst
@@ -0,0 +1,2 @@
+.. include:: ../../CONTRIBUTING.md
+   :parser: myst_parser.sphinx_
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -20,6 +20,7 @@ Overview
 --------
 
 * :doc:`installation`
+* :doc:`include_contributing`
 * :doc:`reference`
 
 :mod:`multigrad`
@@ -55,6 +56,7 @@ Indices and tables
    :hidden:
 
    installation.rst
+   include_contributing.md
    reference.rst