gather contributing docs

docs/contributing/contributing.md

@@ -0,0 +1,81 @@
+Instructions for Contributors
+=============================
+
+Before you submit a [pull request](https://github.com/COSIMA/regional-mom6/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 required dependencies.
+
+We create the environment by calling
+
+```{code-block} bash
+conda env create --prefix ./env --file environment-ci.yml
+```
+
+from the repository's local clone main directory. Then we activate it via
+
+```{code-block} bash
+conda activate ./env
+```
+
+We then install both the package in this environment as well as the `pytest` package:
+
+```{code-block} bash
+python -m pip install .
+python -m pip install pytest
+```
+
+Now we can run the tests with
+
+```{code-block} bash
+python -m pytest tests/
+```
+
+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/
+```
+
+## Documentation
+
+To build the docs from a local clone of the repository we first need to create a conda
+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
+```
+
+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 build the docs via `make`:
+
+```{code-block} bash
+make html
+```
+
+and upon successful build, we preview the documentation by opening `_build/html/index.html`
+in our favorite browser.
+
+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
+pip install -r requirements.txt
+pip install -e ..
+make html
+```

docs/contributing/docker_image_dev.md

@@ -0,0 +1,33 @@
+# Docker Image & Github Testing (For contributors)
+
+regional-mom6 uses a docker image in github actions for holding large data. It wasn't directly being used, but for downloading the curvilinear grid for testing, we are using it. This document is a list of helpful commands to work on it.
+
+The link to the image is at: 
+[https://github.com/COSIMA/regional-mom6/pkgs/container/regional-test-env](https://github.com/COSIMA/regional-mom6/pkgs/container/regional-test-env)
+
+For local development of the image to add data to it for testing, first pull it. 
+```docker pull ghcr.io/cosima/regional-test-env:updated```
+
+Then to do testing of the image, we cd into our cloned version of regional-mom6, and run this command. It mounts our code in the /workspace directory.:
+```docker run -it --rm \ -v $(pwd):/workspace \ -w /workspace \ ghcr.io/cosima/regional-test-env:updated \ /bin/bash```
+
+The -it flag is for shell access, and the workspace stuff is to get our local code in the container.
+You have to download conda, python, pip, and all that business to properly run the tests.
+
+Getting to adding the data, you should create a folder and add both the data you want to add and a file simple called "Dockerfile". In Dockerfile, we'll get the original image, then copy the data we need to the data folder.
+
+```
+# Use the base image
+FROM ghcr.io/cosima/regional-test-env:<tag>
+
+# Copy your local file into the /data directory in the container
+COPY <file> /data/<file>
+```
+
+Then, we need to build the image, tag it, and push it
+
+```
+docker build -t my-custom-image . # IN THE DIRECTORY WITH THE DOCKERFILE
+docker tag my-custom-image ghcr.io/cosima/regional-test-env:<new_tag>
+docker push ghcr.io/cosima/regional-test-env:<new_tag>
+```