JOSS article commit:

* manuscript
* modification and improvement of the documentation and README
* Added tests for a higher dimensional (6x6) model version

README.md

@@ -29,7 +29,7 @@ Installation
 > **__Note:__** qgs is presently compatible with Linux and Mac OS.
 > **It is not compatible with Windows for the moment**, but a Windows compatible version will be released soon.
 
-The easiest way to install is through [Anaconda](https://www.anaconda.com/).
+The easiest way to run qgs is to use an appropriate environment created through [Anaconda](https://www.anaconda.com/).
 
 First install Anaconda and clone the repository:
 
@@ -50,7 +50,7 @@ to see if everything runs smoothly (this should take less than a minute).
 
 In addition to the qgs builtin Runge-Kutta integrator, the qgs model can alternatively be integrated with a package called [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl) written in [Julia](https://julialang.org/), and available through the 
 [diffeqpy](https://github.com/SciML/diffeqpy) python package.
-The diffeqpy pakage first installation step is done by Anaconda in the qgs environment but then you must [install Julia](https://julialang.org/downloads/) and follow the final manual installation instruction found in the [diffeqpy README](https://github.com/SciML/diffeqpy).
+The diffeqpy package first installation step is done by Anaconda in the qgs environment but then you must [install Julia](https://julialang.org/downloads/) and follow the final manual installation instruction found in the [diffeqpy README](https://github.com/SciML/diffeqpy).
 
 These can be summed up as opening a terminal and doing:
 ```
@@ -82,7 +82,7 @@ The documentation is also available online on read the docs: [https://qgs.readth
 Usage
 -----
 
-qgs can be used by editing and running the script `qgs_rp.py` and `qgs_maooam.py` found in the [main folder](./).
+qgs can be used by editing and running the script `qgs_rp.py` and `qgs_maooam.py` found in the main folder.
 
 
 Examples
@@ -119,7 +119,7 @@ Forthcoming developments
 * Technical mid-term developments
     + Dimensionally robust Parameter class operation
     + Windows OS support
-    + Symbolic inner products (using e.g. [Simpy](https://www.sympy.org/))
+    + Symbolic inner products (using e.g. [Sympy](https://www.sympy.org/))
         - Arbitrary spatial mode basis of functions
         - Automatic on-the-fly inner product calculation (numeric or analytic if possible)
         - Symbolic PDE equation specification
@@ -128,6 +128,27 @@ Forthcoming developments
     + Active advection
     + True quasi-geostrophic ocean when using ocean model version
     + Salinity in the ocean
+
+Contributing to qgs
+-------------------
+
+If you want to contribute actively to the roadmap detailed above, please contact the authors.
+
+In addition, if you have made changes that you think will be useful to others, please feel free to suggest these as a pull request on the [qgs Github repository](https://github.com/Climdyn/qgs).
+
+A review of your pull request will follow with possibly suggestions of changes before merging it in the master branch.
+Please consider the following guidelines before submitting:
+* Before submitting a pull request, double check that the branch to be merged contains only changes you wish to add to the master branch. This will save time in reviewing the code.
+* For any changes to the core model files, please run the tests found in the folder [model_test](./model_test) to ensure that the model tensors are still valid.
+* For substantial additions of code, including a test case in the folder [model_test](./model_test) is recommended.
+* Please do not make changes to existing test cases.
+* Please document the new functionalities in the documentation. Code addition without documentation addition will not be accepted. 
+The documentation is done with [sphinx](https://www.sphinx-doc.org/en/master/) and follows the Numpy conventions. Please take a look to the actual code to get an idea about how to document the code.
+* If your addition can be considered as a tool not directly related to the core of the model, please develop it in the toolbox folder.
+* The team presently maintaining qgs is not working full-time on it, so please be patient as the review of the submission may take some time.
+
+For more information about git, Github and the pull request framework, a good source of information is the [contributing guide](https://mitgcm.readthedocs.io/en/latest/contributing/contributing.html) of the [MITgcm](https://github.com/MITgcm/MITgcm).
+
 
 Other atmospheric models in Python
 ----------------------------------

documentation/clean_examples.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-cd source/files/examples
+cd source/files/examples || exit
 
 for file in ./*.ipynb; do
     rm -f ${file%.*}".rst"

documentation/execute_examples.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+cd source/files/examples || exit
+
+for file in ./*.ipynb; do
+    jupyter nbconvert --execute --inplace --ExecutePreprocessor.timeout=600 "$file"
+done
+

documentation/generate_examples.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-cd source/files/examples
+cd source/files/examples || exit
 
 for file in ./*.ipynb; do
     jupyter nbconvert --to rst "$file"

documentation/notes/joss_paper/Makefile

@@ -0,0 +1,56 @@
+# =============================================================================
+# Mefile for generating previews of JOSS paper
+# Original author: Michael Hucka <[email protected]>
+# License: GNU General Public License v3.0 
+# Original project: https://github.com/casics/dassie
+# =============================================================================
+
+# To use this Makefile, you have to install pandoc, xetex and bibstyle. You have also to clone the
+# whedon repository :
+#
+# git clone https://github.com/openjournals/whedon.git
+#
+# in the same directory.
+
+# Change the following values to match your configuration.
+# .............................................................................
+
+input	:= paper.md
+output	:= paper.pdf
+bib	:= joss.bib
+
+# Main code -- no more customization variables after this point
+# .............................................................................
+
+title	:= $(shell grep title: $(input) | sed 's/title: *//' | tr -d "'")
+authors := $(shell sed -n '/authors:/,/affiliations:/p' $(input) | grep name: | sed 's/- name: *//' | paste -d, -s - | sed 's/,/, /g')
+repo	:= $(shell git remote get-url origin | sed 's|[email protected]:|https://github.com/|' | sed 's/\.git//')
+
+$(output): $(input) $(bib) Makefile
+	pandoc \
+	-V paper_title="$(title)" \
+	-V citation_author="$(authors)" \
+	-V repository="$(repo)" \
+	-V archive_doi="http://dx.doi.org/00.00000/zenodo.0000000" \
+	-V formatted_doi="00.00000/joss.00000" \
+	-V paper_url="http://joss.theoj.org/papers/" \
+	-V review_issue_url="http://joss.theoj.org/papers/" \
+	-V issue="0" \
+	-V volume="00" \
+	-V year="2020" \
+	-V submitted="00 January 0000" \
+	-V published="00 January 0000" \
+	-V page="00" \
+	-V graphics="true" \
+	-V logo_path="whedon/resources/joss/logo.png" \
+	-V geometry:margin=1in \
+	-o $(output) \
+    	--pdf-engine=xelatex \
+	--filter pandoc-citeproc $(input) \
+        --csl="whedon/resources/joss/apa.csl" \
+	--from markdown+autolink_bare_uris \
+	--template "whedon/resources/joss/latex.template"
+
+autorefresh:;
+	((ls $(input) $(bib) | entr make $(output)) &)
+