Documentation website for GCBM.Colombia

.gitignore

@@ -0,0 +1,6 @@
+Postprocessing/.Rproj.user
+Postprocessing/.Rhistory
+Postprocessing/.RData
+Postprocessing/.Ruserdata
+Postprocessing/renv/library
+docs/_build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/about_colombia/index.rst

@@ -0,0 +1,32 @@
+About Colombia
+==============
+
+(Source - Wikipedia)
+
+Colombia is a country in South America with an insular region in North America. 
+It is bordered by the Caribbean Sea to the north, Venezuela to the east, 
+Brazil to the southeast, Ecuador and Peru to the south, the Pacific Ocean to the west and 
+Panama to the northwest. Colombia comprises 32 departments and the Capital District of Bogotá, 
+the country's largest city. It covers an area of 1,141,748 square kilometers (440,831 sq mi), with a population of 50 million.
+
+The geography of Colombia is characterized by its six main natural regions that 
+present their own unique characteristics, from the Andes mountain range region 
+shared with Ecuador and Venezuela; the Pacific Coastal region shared with Panama and Ecuador; 
+the Caribbean coastal region shared with Venezuela and Panama; the Llanos (plains) 
+shared with Venezuela; the Amazon rainforest region shared with Venezuela, Brazil, 
+Peru and Ecuador; to the insular area, comprising islands in both the Atlantic and Pacific oceans.
+The climate of Colombia is characterized for being tropical presenting variations within six natural regions 
+and depending on the altitude, temperature, humidity, winds and rainfall. 
+Colombia has a diverse range of climate zones, including tropical rainforests, savannas, steppes, deserts and mountain climates.
+
+Colombia is the second most biologically diverse country on Earth. This biodiversity results 
+from Colombia's varied ecosystems—from the rich tropical rainforest to the coastal cloud 
+forests to the open savannas
+
+.. figure:: ../assets/colombia.gif
+   :alt: Map of Colombia
+   :align: center
+   :width: 405px
+   :height: 486px
+
+   Image source https://geology.com/world/belize-satellite-image.shtml

docs/conf.py

@@ -0,0 +1,52 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'GCBM Colombia'
+copyright = '2022, moja global'
+author = 'moja global'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'furo'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,16 @@
+GCBM Colombia
+=============
+
+This is the official documentation of the GCBM Colombia project. 
+This project is based on the `Standalone Template for the GCBM <https://carbon.nfis.org/cbm>`_ 
+
+**Disclaimer : The calculations performed in this repository are not official and do not represent the Government of Colombia in any way.**
+
+.. toctree::
+   :hidden:
+
+   about_colombia/index.rst
+   run_simulation/index.rst
+   postprocessing/index.rst
+
+

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/postprocessing/index.rst

@@ -0,0 +1,15 @@
+Postprocessing
+==============
+
+After the simulation is complete, either by running the **run_all.bat** script or following the step-by-step procedure, for postprocessing, the following steps are to be followed:
+
+1. Install `R <https://www.r-project.org/>`_ based on the OS
+
+2. Get the path to the R executable, e.g. **c:\\"Program Files"\R\R-4.2.1\bin\R.exe**, on Windows
+
+3. Navigate to the `Standalone_GCBM\\Postprocessing` and execute **c:\\"Program Files"\\R\\R-4.2.1\\bin\\R.exe CMD BATCH Summarize_DOM_Stocks.R** .
+
+This generates the plots `Figures\\Colombia_Sensitivity_TropicalPremontaneWetTransitiontoBasal-Pacific.png`, 
+`Figures\\Colombia_Sensitivity_TropicalMoist.png` and `Figures\\Colombia_Sensitivity_TropicalDry.png`
+
+4. The logs are written into **Summarize_DOM_Stocks.Rout**, missing R packages, if any, can be installed by following the steps mentioned here: https://www.datacamp.com/tutorial/r-packages-guide

docs/requirements.txt

@@ -0,0 +1 @@
+furo

docs/run_simulation/docker.rst

@@ -0,0 +1,59 @@
+On Docker 
+=========
+
+Install Docker and docker-compose based on your `operating system <https://docs.docker.com/engine/install/>`_ . 
+
+Steps to run the Colombia simulation in a docker environment 
+
+1. Clone the `docker-setup` branch of `GCBM Colombia <https://github.com/moja-global/GCBM.Colombia/tree/docker-setup>`_  using the command
+
+..  code-block:: bash
+
+       git clone -b docker-setup https://github.com/moja-global/GCBM.Colombia
+
+
+2. Navigate into `GCBM.Colombia`
+
+..  code-block:: bash
+
+       cd GCBM.Colombia
+
+
+3. Use docker-compose to build the image
+
+..  code-block:: bash
+
+       docker-compose up -d
+
+
+If an error with the following message appears :
+
+`ERROR: Version in "./docker-compose.yml" is unsupported. You might be seeing this error because you're using the wrong Compose file version. Either specify a supported version (e.g "2.2" or "3.3") and place your service definitions under the services key, or omit the version key and place your service definitions at the root of the file to use version 1.
+For more on the Compose file format versions, see https://docs.docker.com/compose/compose-file/`
+
+Change the docker version in the file `./docker-compose.yml` to an appropriate version and run the command again.
+
+
+4. Run the container using the command
+
+..  code-block:: bash
+
+       docker exec -it gcbm-colombia /bin/bash
+
+
+5. Inside the running docker container, run
+
+..  code-block:: bash
+
+       cd /server/gcbm_project
+
+
+6. Start the simulation using
+
+..  code-block:: bash
+
+       /opt/gcbm/moja.cli --config_file gcbm_config.cfg --config_provider provider_config.json
+
+
+If there are existing images cached on your machine you may need to docker pull ghcr.io/moja-global/rest_api_gcbm:master 
+and build the container using `docker-compose -d --force-recreate`

docs/run_simulation/index.rst

@@ -0,0 +1,27 @@
+Running the Colombia simulation 
+===============================
+
+A local simulation of the GCBM model is run for the Colombia region can be run locally.
+
+The repository is located at: https://github.com/moja-global/GCBM.Colombia
+
+.. list-table:: Contents of the repository
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Folder
+     - Description
+   * - Standalone_GCBM
+     - Contains the inputs and scripts required to run the simulation
+   * - Postprocessing
+     - Postprocessing scripts written in R, these operate on the outputs generated by the simulation
+   * - Science
+     - Contains information about the science behind the GCBM model
+
+
+.. toctree::
+   :hidden:
+
+   windows
+   docker 
+