Merge pull request #26 from EcoExtreML/docs_setup

Setting up readthedocs

Author: SarahAlidoost

CONTRIBUTING.md

@@ -1,7 +1,7 @@
-# processing
+# Contributing Guide
 
 This repositary includes python modules for running the STEMMUS-SCOPE model in a
-notebook. 
+notebook.
 
 The workflow is executed using python and MATLAB on a Unix-like system.
 The python packages are listed in the
@@ -17,7 +17,7 @@ Run the commands below in a terminal:
 ```sh
 # Download and install Conda
 wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-pypy3-Linux-x86_64.sh
-bash Mambaforge-pypy3-Linux-x86_64.sh 
+bash Mambaforge-pypy3-Linux-x86_64.sh
 -b -p ~/mamba
 
 # Update base environment
@@ -51,7 +51,7 @@ Snellius, see the script
 on how to load the module.
 </details>
 
-# Run jupyter notebook
+## Run jupyter notebook
 
 **On Snellius:**
 
@@ -69,18 +69,18 @@ interactively.
    "InputPath" and "OutputPath".
 3. click on the `Remote Desktop` in the
 Launcher. Click on the `Applications`. You will find the 'MATLAB' software under
-the `Research`. 
+the `Research`.
 4. After clicking on 'MATLAB', it asks for your account information that is
 connected to a MATLAB license.
 5. Open the file `run_model_in_matlab_dev.m` and set the paths inside the script.
 6. Then, run the main script `run_model_in_matlab_dev.m`.
 
-# Recipe of model execution
+## Recipe of model execution
 
 The execution of the model includes following steps:
 
 - Update/set config files
-- Create input directories, prepare input files 
+- Create input directories, prepare input files
 - Run the model
 - Create output directories, prepare output files
 - Create exe file

README.md

@@ -1,4 +1,3 @@
-# STEMMUS SCOPE Processing
 
 <!-- (Customize these badges with your own links, and check https://shields.io/ or https://badgen.net/ to see which other badges are available.) -->
 
@@ -8,18 +7,18 @@
 [![fair-software badge](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu)
 [![sonarcloud](https://github.com/EcoExtreML/stemmus_scope_processing/actions/workflows/sonarcloud.yml/badge.svg)](https://github.com/EcoExtreML/stemmus_scope_processing/actions/workflows/sonarcloud.yml)
 [![github license badge](https://img.shields.io/github/license/EcoExtreML/stemmus_scope_processing)](https://github.com/EcoExtreML/stemmus_scope_processing)
+[![Documentation Status](https://readthedocs.org/projects/pystemmusscope/badge/?version=latest)](https://pystemmusscope.readthedocs.io/en/latest/?badge=latest)
 
-<!-- [![RSD](https://img.shields.io/badge/rsd-pystemmusscope-00a3e3.svg)](https://www.research-software.nl/software/pystemmusscope) 
-[![workflow pypi badge](https://img.shields.io/pypi/v/pystemmusscope.svg?colorB=blue)](https://pypi.python.org/project/pystemmusscope/) 
+<!-- [![RSD](https://img.shields.io/badge/rsd-pystemmusscope-00a3e3.svg)](https://www.research-software.nl/software/pystemmusscope)
+[![workflow pypi badge](https://img.shields.io/pypi/v/pystemmusscope.svg?colorB=blue)](https://pypi.python.org/project/pystemmusscope/)
 [![DOI](https://zenodo.org/badge/DOI/<replace-with-created-DOI>.svg)](https://doi.org/<replace-with-created-DOI>)
 [![workflow cii badge](https://bestpractices.coreinfrastructure.org/projects/<replace-with-created-project-identifier>/badge)](https://bestpractices.coreinfrastructure.org/projects/<replace-with-created-project-identifier>)
 [![workflow scc badge](https://sonarcloud.io/api/project_badges/measure?project=EcoExtreML_stemmus_scope_processing&metric=coverage)](https://sonarcloud.io/dashboard?id=EcoExtreML_stemmus_scope_processing)
-[![Documentation Status](https://readthedocs.org/projects/stemmus_scope_processing/badge/?version=latest)](https://stemmus_scope_processing.readthedocs.io/en/latest/?badge=latest)
-[![cffconvert](https://github.com/EcoExtreML/stemmus_scope_processing/actions/workflows/cffconvert.yml/badge.svg)](https://github.com/EcoExtreML/stemmus_scope_processing/actions/workflows/cffconvert.yml) 
+[![cffconvert](https://github.com/EcoExtreML/stemmus_scope_processing/actions/workflows/cffconvert.yml/badge.svg)](https://github.com/EcoExtreML/stemmus_scope_processing/actions/workflows/cffconvert.yml)
 [![markdown-link-check](https://github.com/EcoExtreML/stemmus_scope_processing/actions/workflows/markdown-link-check.yml/badge.svg)](https://github.com/EcoExtreML/stemmus_scope_processing/actions/workflows/markdown-link-check.yml) -->
 
-
-This repositary includes python modules for running the STEMMUS-SCOPE model in a notebook. 
+This repositary includes python modules for running the STEMMUS-SCOPE model in a jupyter
+notebook.
 
 The workflow is executed using python and MATLAB Runtime on a Unix-like system.
 The python packages are listed in the
@@ -65,7 +64,7 @@ In a terminal:
 # Download MATLAB Runtime for Linux
 wget https://ssd.mathworks.com/supportfiles/downloads/R2021a/Release/6/deployment_files/installer/complete/glnxa64/MATLAB_Runtime_R2021a_Update_6_glnxa64.zip
 
-# Unzip the file 
+# Unzip the file
 unzip MATLAB_Runtime_R2021a_Update_6_glnxa64.zip
 
 # Install it
@@ -86,7 +85,7 @@ Snellius, see the script
 on how to load the module.
 </details>
 
-# Run jupyter notebook
+## Run jupyter notebook
 
 Open a terminal and run:
 
@@ -109,12 +108,12 @@ interactively.
 Currently, running the notebook on CRIB is not supported because MATLAB Runtime
 can not be installed there.
 
-# Recipe of model execution
+## Recipe of model execution
 
 The execution of the model includes following steps:
 
 - Update/set config files
-- Create input directories, prepare input files 
+- Create input directories, prepare input files
 - Run the model
 - Create output directories, prepare output files
 

docs/conf.py

@@ -17,9 +17,9 @@
 
 # -- Project information -----------------------------------------------------
 
-project = u"PyStemmusScope"
-copyright = u"2022, Netherlands eScience Center"
-author = u"Sarah Alidoost"
+project = "PyStemmusScope"
+copyright = "2022, Netherlands eScience Center"
+author = "Sarah Alidoost"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -76,6 +76,20 @@
 #
 # html_theme_options = {}
 
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    "**": [
+        'globaltoc.html',
+        "relations.html",  # needs 'show_related': True theme option to display
+        "searchbox.html",
+    ]
+}
+
+
 # -- Options for Intersphinx
 
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),

docs/contributing_link.rst

@@ -0,0 +1,2 @@
+.. include:: ../CONTRIBUTING.md
+   :parser: myst_parser.sphinx_

docs/index.rst

@@ -3,16 +3,25 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to PyStemmusScope's documentation!
-==========================================================
+PyStemmusScope documentation
+****************************
 
-.. toctree::
-  :maxdepth: 2
-  :caption: Contents:
+Welcome to the documentation of PyStemmusScope, a python package that enables researchers
+to use the MATLAB-based STEMMUS-SCOPE model.
+
+`STEMMUS-SCOPE <https://gmd.copernicus.org/articles/14/1379/2021/>`_ is an integrated
+soil-plant-atmosphere continuum model based on the models
+`SCOPE <https://github.com/Christiaanvandertol/SCOPE/>`_ and
+`STEMMUS <https://blog.utwente.nl/stemmus/introduction/>`_, and models
+canopy photosynthesis, fluorescence, and the transfer of energy, mass, and momentum.
 
-Indices and tables
-==================
+For a guide on how to setup and run the model, see the :doc:`user guide <readme_link>`.
+If you are interested in contributing to the PyStemmusScope code, see the
+:doc:`contributing guide <contributing_link>`.
+
+.. toctree::
+  :maxdepth: 0
+  :hidden:
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+  User guide <readme_link>
+  Contributing guide <contributing_link>

docs/readme_link.rst

@@ -0,0 +1,4 @@
+User Guide
+**********
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_