Merge pull request #44 from COSIMA/ncc/add-instructions-to-build-docs

Add instructions to run tests + build docs locally

.gitignore

@@ -1,5 +1,8 @@
 __pycache__
 .ipynb_checkpoints
 build
+_build
 mom6_regional/_version.py
 mom6_regional.egg-info
+.pytest_cache
+env

docs/contributing.md

@@ -0,0 +1,65 @@
+Instructions for Contributors
+=============================
+
+Before you submit a [pull request](https://github.com/COSIMA/mom6-regional/pulls) it's always a
+good idea to run the tests locally and catch any potential bugs/errors that might have been
+introduced. Also, sometimes it's also a good idea to build the documentation locally to see
+how new docstrings or any new bits of documentation that you may have added look like.
+
+
+## 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
+
+```{code-block} bash
+conda env create --prefix ./env --file environment-ci.yml
+```
+
+and then activate it
+
+```{code-block} bash
+conda activate ./env
+```
+
+Now we need to install the package in this environment as well as `pytest`
+
+```{code-block} bash
+python -m pip install .
+python -m pip install pytest
+```
+
+Now we can run the test with
+
+```{code-block} bash
+python -m pytest tests/
+```
+
+## 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 
+
+```{code-block} bash
+cd docs
+conda create --name docs-env --file requirements.txt
+```
+
+Then activate this environment and run `make`:
+
+```{code-block} bash
+conda activate docs-env
+make html
+```
+
+and open `_build/html/index.html` in your favorite browser.
+
+Alternatively, we can also install the dependencies needed for the docs via `pip`.
+
+```{code-block} bash
+cd docs
+pip install -r docs/requirements.txt
+make html
+```

docs/index.rst

@@ -5,6 +5,7 @@ Welcome to MOM6 Regional's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   contributing
    api