Merge branch 'main' into fixing-docs-warnings

.all-contributorsrc

@@ -1,6 +1,6 @@
 {
   "projectName": "deepsensor",
-  "projectOwner": "tom-andersson",
+  "projectOwner": "alan-turing-institute",
   "skipCI": true,
   "files": [
     "README.md"
@@ -168,6 +168,17 @@
       "contributions": [
         "ideas"
       ]
+    },
+    {
+      "login": "JimCircadian",
+      "name": "Jim Circadian",
+      "avatar_url": "https://avatars.githubusercontent.com/u/731727?v=4",
+      "profile": "http://inconsistentrecords.co.uk",
+      "contributions": [
+        "ideas",
+        "projectManagement",
+        "maintenance"
+      ]
     }
   ]
 }

.gitignore

@@ -10,3 +10,4 @@ dist/*
 .tox/
 _build
 *.png
+deepsensor.egg-info/

CITATION.cff

@@ -11,9 +11,9 @@ authors:
   - given-names: Tom Robin
     family-names: Andersson
     email: [email protected]
-    affiliation: British Antarctic Survey
+    affiliation: Google DeepMind
     orcid: 'https://orcid.org/0000-0002-1556-9932'
-repository-code: 'https://github.com/tom-andersson/deepsensor'
+repository-code: 'https://github.com/alan-turing-institute/deepsensor'
 abstract: >-
   DeepSensor is a Python package for modelling environmental
   data with convolutional neural processes (ConvNPs).
@@ -38,5 +38,5 @@ keywords:
   - neural processes
   - active learning
 license: MIT
-version: 0.3.2
-date-released: '2023-10-18'
+version: 0.3.6
+date-released: '2024-02-02'

CONTRIBUTING.md

@@ -42,10 +42,10 @@ us at [email protected].
 
 ## How to Contribute
 
-We welcome contributions of all kinds, be it code, documentation, or community engagement. We
+We welcome contributions of all kinds, be it code, documentation, raising issues, or community engagement. We
 encourage you to read through the following sections to learn more about how you can contribute to
 
-## How to Submit Changes
+### How to Submit Changes
 
 We follow the same instructions for submitting changes to the project as those developed
 by [The Turing Way](https://github.com/the-turing-way/the-turing-way/blob/main/CONTRIBUTING.md#making-a-change-with-a-pull-request).
@@ -57,7 +57,7 @@ In short, there are five steps to adding changes to this repository:
 3. **Commit and Push**: Use clear commit messages.
 4. **Open a Pull Request**: Ensure you describe the changes made and any additional details.
 
-### 1. Fork the Repository
+#### 1. Fork the Repository
 
 Once you have [created a fork of the repository](https://github.com/tom-andersson/deepsensor/fork),
 you now have your own unique local copy of DeepSensor. Changes here won't affect anyone else's work,
@@ -70,7 +70,7 @@ If you prefer working with GitHub in the
 browser, [these instructions](https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser)
 describe how to sync your fork to the original repository.
 
-### 2. Make Changes
+#### 2. Make Changes
 
 Try to keep the changes focused.
 If you submit a large amount of work all in one go it will be much more work for whoever is
@@ -82,7 +82,7 @@ Check out
 our [Version Control chapter](https://the-turing-way.netlify.com/version_control/version_control.html)
 in _The Turing Way_ Book!
 
-### 3. Commit and Push
+#### 3. Commit and Push
 
 While making your changes, commit often and write good, detailed commit messages.
 [This blog](https://chris.beams.io/posts/git-commit/) explains how to write a good Git commit
@@ -96,7 +96,7 @@ That is, please do not use the [rebase](https://help.github.com/en/articles/abou
 command to edit previous commit messages, combine multiple commits into one, or delete or revert
 commits that are no longer necessary.
 
-### 4. Open a Pull Request
+#### 4. Open a Pull Request
 
 We encourage you to open a pull request as early in your contributing process as possible.
 This allows everyone to see what is currently being worked on.
@@ -106,6 +106,52 @@ continuous integration as you make commits (which will help prevent stuff from b
 GitHub has a [nice introduction](https://guides.github.com/introduction/flow) to the pull request
 workflow, but please [get in touch](#get-in-touch) if you have any questions :balloon:.
 
+### DeepSensor's documentation
+
+You don't have to write code to contribute to DeepSensor.
+Another highly valuable way of contributing is helping with DeepSensor's [documentation](tom-andersson.github.io/deepsensor/).
+See below for information on how to do this.
+
+#### Background
+
+We use the Jupyter Book framework to build our documentation in the `docs/` folder.
+The documentation is written in
+Markdown and Jupyter Notebooks. The documentation is hosted on GitHub Pages and is automatically
+built and deployed using GitHub Actions after every commit to the `main` branch.
+
+DeepSensor requires slightly unique documentation, because demonstrating the package requires
+both data and trained models.
+This makes it compute- and data-hungry to run some of the notebooks, and they cannot
+run on GitHub Actions.
+Therefore, all the notebooks are run locally - the code cell outputs are saved in the .ipynb files
+and are rendered when the documentation is built.
+If DeepSensor is updated, some of the notebooks may become out of date and will need to be re-run.
+
+Some relevant links for Juptyer Book and MyST:
+* https://jupyterbook.org/en/stable/intro.html
+* https://jupyterbook.org/en/stable/content/myst.html
+* https://jupyterbook.org/en/stable/reference/cheatsheet.html
+
+#### Contributing to documentation
+
+One easy way to contribute to the documentation is to provide feedback in [this issue](https://github.com/tom-andersson/deepsensor/issues/87) and/or in the DeepSensor Slack channel.
+
+Another way to contribute is to directly edit or add to the documentation and open a PR:
+* Follow all the forking instructions above
+* Install the documentation requirements: `pip install -r requirements/requirements.docs.txt`
+* Option A: Editing a markdown file
+  * Simply make your edits!
+* Option B: Editing a jupyter notebook file
+  * This can be more involved... Firstly, reach out on the Slack channel to ask if anyone else is working on the same notebook file locally. Working one-at-a-time can save Jupyter JSON merge conflict headaches later!
+  * If you are only editing markdown cells, just re-run those cells specifically to compile them
+  * If you are editing code cells:
+    * Install `cartopy` using `conda install -c conda-forge cartopy`
+    * Run the all the code cells that the current cell depends on and any subsequent code cells that depend on the current cell (you may need to rerun the whole notebook)
+    * Note: Some notebooks require a GPU and some assume that previous notebooks have been run
+  * Please be careful about not clearing any code cell outputs that you don't intend to!
+* Once your changes have been made, regenerate the docs locally with `jupyter-book build docs --all` and check your changes have applied as expected
+* Push your changes and open a PR (see above)
+
 ## First-timers' Corner
 
 If you're new to the project, we recommend starting with issues labeled