documentation

.gitignore

@@ -285,3 +285,7 @@ modules.xml
 .idea/sonarlint
 
 # End of https://www.toptal.com/developers/gitignore/api/node,linux,macos,terraform,webstorm+all,visualstudiocode
+
+# Sphinx documentation 
+docs/build
+docs/venv/

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     = source
+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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+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.https://www.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/requirements.txt

@@ -0,0 +1,7 @@
+Sphinx
+pydata-sphinx-theme
+sphinx-notfound-page
+sphinxcontrib-images
+sphinx-icon
+sphinx-btn
+sphinxcontrib-youtube

docs/source/404.rst

@@ -0,0 +1,14 @@
+:orphan:
+
+404 not found
+=============
+
+.. image:: _static/img/404-compass.png
+    :align: left
+    :width: 40%
+
+UH OH! You're lost.
+-------------------
+
+The page you are looking for does not exist.
+How you got here is a mystery. But you can click the SEPAL button on top of the page to go back to the homepage.

docs/source/_static/css/custom.css

@@ -0,0 +1,25 @@
+/*******************************************************************************
+*   text justification
+*
+**/
+p {text-align: justify;}
+
+/*********************************************************************************
+*   change the lightbox cursor
+*
+**/
+a[data-lightbox] {cursor: zoom-in;}
+a[data-lightbox] img {padding: .25em;}
+
+/*********************************************************************************
+*  make the footer inlined
+*
+**/
+.footer-item {
+   display: inline-block;
+}
+.footer-item:not(:last-child) {
+   border-right: 1px solid rgba(var(--pst-color-text-base), 1);
+   margin-right: .5em;
+   padding-right: .5em;
+ }

docs/source/_templates/license.html

@@ -0,0 +1,6 @@
+<!-- display the licensing information in the footer -->
+<a href="https://creativecommons.org/licenses/by-sa/2.0/legalcodeE">
+    <i class="fab fa-creative-commons"></i>
+    <i class="fab fa-creative-commons-by"></i>
+    <i class="fab fa-creative-commons-sa"></i>
+</a>

docs/source/conf.py

@@ -0,0 +1,100 @@
+# 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
+
+from datetime import datetime
+
+
+# -- Project information -------------------------------------------------------
+
+project = "Arena"
+copyright = f"2018-{datetime.now().year}, Open Foris"
+author = "Open Foris"
+release = "1.0.24"
+
+# -- 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 = [
+    "sphinxcontrib.images",
+    "sphinxcontrib.icon",
+    "sphinxcontrib.btn",
+    "sphinxcontrib.youtube",
+    "notfound.extension",
+]
+
+# 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 = ["**.ipynb_checkpoints"]
+
+
+# -- 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 = "pydata_sphinx_theme"
+
+# 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"]
+
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = ["css/custom.css"]
+
+# -- Pydata-sphinx-theme parameters --------------------------------------------
+
+# A complete description of the theme can be found on their documentation: 
+# https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html
+
+html_favicon = "_static/img/favicon.ico"
+
+html_logo = "_static/img/arena-logo.png"
+
+html_theme_options = {
+    "navigation_with_keys": False,
+    "show_prev_next": False,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/openforis/arena",
+            "icon": "fab fa-github"
+        },
+        {
+            "name": "Twitter",
+            "url": "https://twitter.com/OpenForis",
+            "icon": "fab fa-twitter"
+        },
+        {
+             "name": "Website",
+            "url": "https://www.openforis-arena.org/app/home/",
+            "icon": "fas fa-globe"
+        }
+    ],
+    "use_edit_page_button": True,
+    "footer_items": ["copyright", "sphinx-version", "license"]
+}
+
+html_context = {
+    "github_user": "openforis",
+    "github_repo": "arena",
+    "github_version": "master",
+    "doc_path": "docs/source"
+}
+
+# -- Options for images --------------------------------------------------------
+
+images_config = {
+    "download": False,
+    "override_image_directive": True
+}

docs/source/cookbook/index.rst

@@ -0,0 +1,12 @@
+Cookbook
+========
+
+This is the entry-point of the cookbook section where you'll learn to use our tool
+
+.. important::
+
+   The documenation is under heavy construction !
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:

docs/source/index.rst

@@ -0,0 +1,16 @@
+Welcome to Arena's documentation!
+=================================
+
+.. important::
+
+   The documenation is under heavy construction ! 
+
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   start/index
+   usage/index
+   cookbook/index
+

docs/source/start/aknowledgment.rst

@@ -0,0 +1,2 @@
+aknowledgment
+=============

docs/source/start/custom.rst

@@ -0,0 +1,112 @@
+Custom instructions
+===================
+
+Introduction
+------------
+
+The :code:`doc` has a fixed structure that needs to be respected to stay inline withe Sphinx builder requirements. All modification should be made in the :code:`docs/source/` folder and the images associated with a page should live in the corresponding folder in :code:`sepal-doc/docs/source/_static/img/`.
+
+If some of the files are misplaced there build into html pages cannot be guaranteed. Please respect the following instructions when you consider making changes to the repository. 
+
+Tools
+^^^^^
+
+The work of the :code:`docs/` folder is to create .rst files in an ordered way. To do that will will use at it's maximum the potential of the Python `Sphinx <https://www.sphinx-doc.org/en/master/>`__ library (to create the build) and the `ReadTheDoc <https://readthedocs.org>`__ website (to distribute the build).
+
+.. warning::
+
+    To work on this project you will need the following:
+
+    - basic knowledge of any lightweight markup language ( markdown, latex, etc..) that will help you understand .rst
+    - the `Sphinx directives documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
+    - a GitHub account 
+    - basic understanding of terminal commands 
+
+Guidelines
+^^^^^^^^^^
+
+There are very few guidelines to respect that are not directly specified by the .rst documentation or the template. 
+
+-    In all the files you write please respect the following indentation: :code:`4 spaces`. it includes directives (option and content) AND bullet points
+-    For the headings of your files use the following symbols (from heading 1 to heading 6) :code:`=`, :code:`-`, :code:`^`, :code:`"`, :code:`#`, :code:`+`. If not respected then the latex build will be funny.
+
+Custom directives and roles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here you will find the custom directives that have been added to help us build our documentation: 
+
+videos
+""""""
+
+ReST directive for embedding Youtube and Vimeo videos (https://github.com/sphinx-contrib/youtube).
+There are two directives added: :code:`youtube` and :code:`vimeo`. The only argument is the video id of the video to include.
+Both directives have three optional arguments: 
+- :code:`height`, 
+- :code:`width`,
+- :code:`align`
+
+Default height is **281** and default width is **500**. By default the video will be aligned on the **left** side.
+
+Here you'll find an example: 
+
+.. code-block:: rst 
+
+    .. youtube:: Ub6N8aWThw4
+        :height: 315
+        :width: 560
+
+.. youtube:: Ub6N8aWThw4
+    :height: 315
+    :width: 560
+
+icon
+""""
+
+ReST role to include inline icons in the documenation (https://sphinx-icon.readthedocs.io/en/latest/?badge=latest). You can find the icon you're looking for in the fontawesome library `page <https://fontawesome.com/v5.15/icons?d=gallery&p=2>`__. (
+
+.. code-block:: rst 
+
+    I'm a folder icon: :icon:`fa fa-folder`
+
+I'm a folder icon: :icon:`fa fa-folder`
+
+btn
+"""
+
+Rest role to include complete btn in the documentation (https://sphinx-btn.readthedocs.io/en/latest/?badge=latest). You can find the icon you're looking for in the fontawesome library `page <https://fontawesome.com/v5.15/icons?d=gallery&p=2>`__. The text is optional.
+
+.. code-block:: rst 
+
+    I'm a apply btn: :btn:`<fas fa-check> apply`
+
+    I'm the app btn: :btn:`<fas fa-wrench>`
+
+I'm a apply btn: :btn:`<fas fa-check> apply`
+
+I'm the app btn: :btn:`<fas fa-wrench>`
+
+image
+"""""
+
+We decided to include a lib to overwrite the image directive. With this extention, image can be zoomed-in using the fantastic lightbox javascript solution. nothing to change from your side simply avoid the :code:`target` parameter in your image and forget about the `figure` directive (because it cannot be overwritten). Documentation can be found here: https://sphinxcontrib-images.readthedocs.io/en/latest/. You can use the :code:`group` option to navigate between images using the keyboard arrows.
+
+
+.. code-block:: rst 
+
+    .. image:: http://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
+        :width: 30%
+        :group: toto
+
+    .. image:: http://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
+        :width: 30%
+        :group: toto
+
+.. image:: http://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
+    :width: 30%
+    :group: toto
+
+.. image:: http://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
+    :width: 30%
+    :group: toto
+
+

docs/source/start/index.rst

@@ -0,0 +1,17 @@
+Getting started
+===============
+
+This is the entry-point of the Getting started section where you'll learn to use our tool
+
+.. important::
+
+   The documenation is under heavy construction !
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   register
+   aknowledgment
+   kitchen-sink
+   custom