Move docs to mkdocs, include notebook w/ source link (#64)

* Update to docs, include notebook w/ source link

* Add nbsphinx to dev dependencies

* Disable "edit on github".

* Add extra links to ToC

* Update logo. Try prolog

* Update docstrings, notebooks

* Move to mkdocs

* Set rtd config to use mkdocs

* Fix docs build, use mkdocs

* Remove duplicate notebooks from main dir

* Update readme, dependencies, gitignore

Author: BSchilperoort

.github/workflows/documentation.yml

@@ -30,7 +30,6 @@ jobs:
           python3 -m pip install --upgrade pip setuptools
           python3 -m pip install .[dev,publishing]
       - name: Install pandoc using apt
-        run: sudo apt install pandoc        
+        run: sudo apt install pandoc
       - name: Build documentation
-        run: make coverage doctest html
-        working-directory: docs
+        run: mkdocs build

.gitignore

@@ -72,9 +72,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 target/
 

.readthedocs.yaml

@@ -5,6 +5,10 @@ build:
   tools:
     python: "3.9"
 
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
+
 python:
   install:
     - method: pip

PyStemmusScope/save.py

@@ -1,18 +1,19 @@
 """PyStemmusScope save module.
 
-Module designed to create a netcdf file following `ALMA
-convention <https://web.lmd.jussieu.fr/~polcher/ALMA/>`_ from csv files following
-`SCOPE format <https://scope-model.readthedocs.io/en/latest/outfiles.html>`_ in
-the output directory.
+Module designed to create a netcdf file following the
+[ALMA convention](https://web.lmd.jussieu.fr/~polcher/ALMA/)
+from csv files following the
+[SCOPE format](https://scope-model.readthedocs.io/en/latest/outfiles.html)
+in the output directory.
 
 The file
-`required_netcf_variables.csv <https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/utils/csv_to_nc/required_netcf_variables.csv>`_
-lists required variable names and their attributes based on `ALMA+CF
-convention table <https://docs.google.com/spreadsheets/d/1CA3aTvI9piXqRqO-3MGrsH1vW-Sd87D8iZXHGrqK42o/edit#gid=2085475627>`_.
+[`required_netcf_variables.csv`](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/utils/csv_to_nc/required_netcf_variables.csv)
+lists required variable names and their attributes based on the
+[ALMA+CF convention table](https://docs.google.com/spreadsheets/d/1CA3aTvI9piXqRqO-3MGrsH1vW-Sd87D8iZXHGrqK42o/edit#gid=2085475627).
 
-Example:
-    See notebooks/run_model_in_notebook.ipynb in
-    `STEMMUS_SCOPE_Processing repository <https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing>`_
+Note:
+    See notebooks/run_model_in_notebook.ipynb in the
+    [STEMMUS_SCOPE_Processing repository](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing).
 
 """
 import logging
@@ -182,10 +183,10 @@ def _update_dataset_attrs_dims(dataset: xr.Dataset, forcing_dict: Dict) -> xr.Da
     """Update dimentions of a dataset according to ALMA conventions.
 
     Args:
-        dataset(xr.Dataset): a dataset with varaibles in ALMA conventions.
+        dataset: a dataset with varaibles in ALMA conventions.
 
     Returns:
-        xr.Dataset: the dataset with dimensions ("time", "x", "y").
+        The dataset with dimensions ("time", "x", "y").
     """
 
     # add x/y dims to the dataset
@@ -237,11 +238,11 @@ def to_netcdf(config_file: str, cf_filename: str) -> str:
         information provided by ALMA conventions.
 
     Args:
-        config_file(str): Path to the config file.
-        cf_filename(str): Path to a csv file for ALMA conventions.
+        config_file: Path to the config file.
+        cf_filename: Path to a csv file for ALMA conventions.
 
     Returns:
-        str: path to a csv file under the output directory.
+        Path to a csv file under the output directory.
     """
     config = config_io.read_config(config_file)
     forcing_filename = utils.get_forcing_file(config)

PyStemmusScope/stemmus_scope.py

@@ -34,7 +34,7 @@ def _is_model_src_exe(model_src_path: Path):
     msg = (
         "Provide a valid path to an executable file or "
         "to a directory containing model source codes, "
-        "see the `documentaion<https://pystemmusscope.readthedocs.io/>`_.")
+        "see the `documentation<https://pystemmusscope.readthedocs.io/>`_.")
     raise ValueError(msg)
 
 
@@ -43,7 +43,7 @@ def _check_interpreter(interpreter: str):
         msg = (
             "Set `interpreter` as Octave or Matlab to run the model using source codes."
             "Otherwise set `model_src_path` to the model executable file, "
-            "see the `documentaion<https://pystemmusscope.readthedocs.io/>`_.")
+            "see the `documentation<https://pystemmusscope.readthedocs.io/>`_.")
         raise ValueError(msg)
 
 
@@ -73,22 +73,24 @@ def _run_sub_process(args: list, cwd):
 
 class StemmusScope():
     """PyStemmusScope wrapper around Stemmus_Scope model.
-    see https://gmd.copernicus.org/articles/14/1379/2021/
 
-   Configures the model and prepares forcing and soil data for the model run.
+    For a detailed model description, look at
+    [this publication](https://gmd.copernicus.org/articles/14/1379/2021/).
 
-    Args:
-        config_file(str): path to Stemmus_Scope configuration file. An example
-        config_file can be found in tests/test_data in `STEMMUS_SCOPE_Processing
-        repository <https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing>`_
-        model_src_path(str): path to Stemmus_Scope executable file or to a
-        directory containing model source codes.
-        interpreter(str, optional): use `Matlab` or `Octave`. Only required if
-        `model_src_path` is a path to model source codes.
+    Configures the model and prepares forcing and soil data for the model run.
+
+    Arguments:
+        config_file (str): Path to Stemmus_Scope configuration file. An example
+            config_file can be found in tests/test_data in [STEMMUS_SCOPE_Processing
+            repository](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing).
+        model_src_path (str): Path to Stemmus_Scope executable file or to a
+            directory containing model source codes.
+        interpreter (str, optional): Use `Matlab` or `Octave`. Only required if
+            `model_src_path` is a path to model source codes.
 
     Example:
-        See notebooks/run_model_in_notebook.ipynb in `STEMMUS_SCOPE_Processing
-        repository <https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing>`_
+        See notebooks/run_model_in_notebook.ipynb at the [STEMMUS_SCOPE_Processing
+        repository](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing)
     """
 
     def __init__(self, config_file: str, model_src_path: str, interpreter: str = None):
@@ -121,12 +123,13 @@ def setup(
         1. Creates config file and input/output directories based on the config template.
         2. Prepare forcing and soil data
 
-        Args:
+        Arguments:
             WorkDir: path to a directory where input/output directories should be created.
             ForcingFileName: forcing file name. Forcing file should be in netcdf format.
-            StartTime: Start time of the model run. It must be in 
+            StartTime: Start time of the model run. It must be in
                 ISO format (e.g. 2007-01-01T00:00).
-            EndTime: End time of the model run. It must be in ISO format (e.g. 2007-01-01T00:00).
+            EndTime: End time of the model run. It must be in ISO format
+                (e.g. 2007-01-01T00:00).
 
         Returns:
             Path to the config file
@@ -163,7 +166,7 @@ def run(self) -> str:
         Args:
 
         Returns:
-            string, the model log
+            The model log.
         """
         if self.exe_file:
             # run using MCR

README.md

@@ -26,158 +26,8 @@ The model source code, executable file and utility files are available in the [S
 
 The input datasets are available on Snellius and CRIB. First, make sure you have
 right access to the repository and data. Then, see the notebook
-[run_model_in_notebook.ipynb](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/blob/main/notebooks/run_model_in_notebook.ipynb)
-which provides different options to run the model, see [Run the
-model](#run-the-model).
+[run_model_in_notebook.ipynb](https://pystemmusscope.readthedocs.io/en/latest/readme_link.html)
+which provides different options to run the model.
 
-## Run the model
-
-1. Using executable file: As a user, you don't need to have a MATLAB license to
-run the STEMMUS-SCOPE model. If `PyStemmusScope` and `MATLAB Runtime` are
-installed on a Unix-like system (e.g. your own machine, Snellius or WSL), you
-can run STEMMUS_SCOPE using the executable file.
-2. Using Matlab: If `PyStemmusScope` and `Matlab` are installed, you can run
-STEMMUS_SCOPE from the source code, for example on Snellius or CRIB.
-3. Using Octave: If `PyStemmusScope` and latest `Octave` including required
-packages are installed, you can run STEMMUS_SCOPE from its source code, for
-example on CRIB or your own machine.
-
-See section [Installations](#installations) for required packages.
-
-## Installations
-
-### On Snellius
-
-[Snellius](https://servicedesk.surfsara.nl/wiki/display/WIKI/Snellius) is the
-Dutch National supercomputer hosted at SURF. MATLAB and MATLAB Runtime are
-installed on Snellius, see the script
-[`run_jupyter_lab_snellius.sh`](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/blob/main/run_jupyter_lab_snellius.sh)
-on how to load the module. Also, use the same script to create a jupyter lab
-server for running notebooks interactively. The script activates the conda
-environment `pystemmusscope`. Make sure that you create the `pystemmusscope`
-conda environment before submitting the the bash script. See
-[Create pystemmusscope conda environment](#create-pystemmusscope-conda-environment).
-
-### On CRIB
-
-[CRIB](https://crib.utwente.nl/) is the ITC Geospatial Computing Platform. You
-can run the model using `Matlab` or `Octave`. Currently, running the
-exceutable file on CRIB is not supported because MATLAB Runtime can not be
-installed there. See [Install PyStemmusScope](#install-pystemmusscope).
-
-### On your own machine
-
-Choose how do you want to run the model, see [Run the model](#run-the-model).
-
-### Install PyStemmusScope
-
-Run the commands below in a terminal (On Windows, use `python` instead of
-`python3`):
-
-```sh
-python3 -m pip install pystemmusscope
-```
-
-or
-
-Open a jupyter notebook and run the code below in a cell:
-
-```python
-!pip install pystemmusscope
-```
-
-### Install jupyterlab
-
-Jupyterlab is needed to run notebooks. Run the commands below in a terminal:
-
-```sh
-python3 -m pip install jupyterlab
-
-```
-
-Open a terminal, make sure the environment is activated. Then, run `jupyter lab`:
-
-```sh
-jupyter lab
-```
-
-JupyterLab will open automatically in your browser. Now, you can run the
-notebook
-[run_model_in_notebook.ipynb](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/blob/main/notebooks/run_model_in_notebook.ipynb).
-
-### Install MATLAB Runtime
-
-To run the STEMMUS_SCOPE, you need MATLAB Runtime version `2021a` and a Unix-like system.
-
-In a terminal:
-
-```sh
-# 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 MATLAB_Runtime_R2021a_Update_6_glnxa64.zip -d MATLAB_Runtime
-
-# Install it
-cd MATLAB_Runtime
-sudo -H ./install -mode silent -agreeToLicense yes
-```
-
-For more information on how to download and install MATLAB Runtime, see the links below:
-  - [download](https://nl.mathworks.com/products/compiler/matlab-runtime.html)
-  - [installation](https://nl.mathworks.com/help/compiler/install-the-matlab-runtime.html)
-
-### Install WSL
-
-As the STEMMUS-SCOPE executable only supports Unix-like systems, Windows users
-cannot run STEMMUS-SCOPE natively. However, users of Windows 10 and newer can
-use WSL ([Windows Subsystem for
-Linux](https://docs.microsoft.com/en-us/windows/wsl/)) to run the model.
-Check the <a
-href="https://docs.microsoft.com/en-us/windows/wsl/install">Microsoft Guide</a>
-for a compatibility information and for general WSL instructions.
-If no installation exists, a Ubuntu distribution can be installed using the following commands:
-```sh
-wsl --install
-```
-
-After installation, you can start up the WSL instance and update the default software:
-
-```sh
-sudo apt update && sudo apt upgrade
-```
-
-You can now set up a python environment using either python's `venv`, or use Conda/Mamba.
-Note that the command to run python and pip can be `python3` and `pip3` by default.
-
-For the rest of the installation instructions simply follow the steps below.
-Note that it is possible to access files from the Windows filesystem from within
-WSL, by accessing, e.g., `/mnt/c/` instead of `C:\`. This means that large input
-data files can be stored on your Windows installation instead of inside the WSL
-distro. However, WSL does not have write permission. Therefore, output data will
-be stored within WSL. Make sure that `WorkDir` in the model config file is set
-correctly.
-
-### Create pystemmusscope conda environment
-
-If a conda environment is neeed, run the commands below in a terminal:
-
-```sh
-# Download and install Mamba on linux
-wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-pypy3-Linux-x86_64.sh
-bash Mambaforge-pypy3-Linux-x86_64.sh -b -p ~/mamba
-
-# Update base environment
-. ~/mamba/bin/activate
-mamba update --name base mamba
-
-# Download environment file
-wget https://raw.githubusercontent.com/EcoExtreML/STEMMUS_SCOPE_Processing/main/environment.yml
-
-# Create a conda environment called 'pystemmusscope' with all required dependencies
-mamba env create -f environment.yml
-
-# The environment can be activated with
-. ~/mamba/bin/activate pystemmusscope
-
-```
+More information on the setup and installation, including for own machine, is available
+in the [documentation](https://pystemmusscope.readthedocs.io/).

CONTRIBUTING.md docs/CONTRIBUTING.mdCONTRIBUTING.md renamed to docs/CONTRIBUTING.md

@@ -1,6 +1,8 @@
 # Contributing Guide
 
-This repository includes the python package `PyStemmusScope` for running the STEMMUS-SCOPE model.
+If you want to contribute to `PyStemmusScope`, you will need to set up your development
+environment the right way. The instructions below will guide you though the steps
+required.
 
 ## Configure the python package for development and testing
 
@@ -23,7 +25,7 @@ cd STEMMUS_SCOPE_Processing
 python3 -m install -e .[dev]
 ```
 
-### Run tests
+### Running tests
 
 The testing framework used here is [PyTest](https://pytest.org). You can run
 tests as (On Windows, use `python` instead of `python3`):
@@ -32,16 +34,18 @@ tests as (On Windows, use `python` instead of `python3`):
 python3 -m pytest
 ```
 
-### Build documentation
+### Building the documentation
 
-To build the documentation locally:
+To edit the documentation locally, do:
 
 ```sh
-cd docs/
-make html
+mkdocs serve
 ```
 
-Then open `_build/html/index.html` in a web broser to preview the documentation.
+Then open the local hyperlink displayed in the terminal, e.g.:
+```
+INFO     -  [13:23:44] Serving on http://127.0.0.1:8000/
+```
 
 ### Run formatting tools