Merge branch '24-generate-documentation' into dev

README.md

@@ -143,7 +143,7 @@ $ udocker run --user=application o3skim --help
 # Authors <a name = "authors"></a>
 - [@V.Kozlov](https://git.scc.kit.edu/eo9869) - TBD
 - [@T.Kerzenmacher](https://git.scc.kit.edu/px5501) - TBD
-- [@B.steban](https://git.scc.kit.edu/zr5094) - TBD
+- [@B.Esteban](https://git.scc.kit.edu/zr5094) - TBD
 
 # Acknowledgements <a name = "acknowledgement"></a>
 - 

docs/.gitignore

+### Documentation builds 
+_build
+_static
+_templates
+

docs/Makefile

+# 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/conf.py

+# 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 = 'o3skim'
+copyright = '2020, T.Kerzenmacher, V.Kozlov, B.Esteban'
+author = 'T.Kerzenmacher, V.Kozlov, B.Esteban'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1.0'
+
+
+# -- 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 = [
+    'sphinx.ext.autodoc'
+]
+
+# 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 = 'alabaster'
+
+# 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']
\ No newline at end of file

docs/dev_guide/local-install.rst

+Local installation
+==================================
+
+To run tests, you need to install the tool in your system without docker.
+
+As first step ensure you have the following dependencies:
+ - python_ > 3.8
+ - pip_ > 20.0.2
+ - gcc_
+ - g++_
+
+After downloading the repository and installing dependencies check, install with pip:
+
+.. code-block:: bash
+
+    $ pip install -e .
+
+
+.. _python: https://www.python.org
+.. _pip: https://pypi.org
+.. _gcc: https://gcc.gnu.org
+.. _g++:
+

docs/dev_guide/tests.rst

+Tests
+==================================
+
+Tests should run using tox_
+
+.. _tox: https://tox.readthedocs.io/en/latest/
+
+
+To install it with pip use:
+
+.. code-block:: bash
+    
+    $ pip install tox
+
+
+To start testing simply run:
+
+.. code-block:: bash
+
+    $ tox
+    ...
+    py37: commands succeeded
+    py38: commands succeeded
+

docs/getting_started/build.rst

+Build
+===================
+
+Download the repository at the **Build machine** using git.
+
+.. code-block:: bash
+
+    $ git clone git@git.scc.kit.edu:synergy.o3as/o3skim.git
+    Cloning into 'o3skim'...
+    ...
+
+
+Build the container image at the **Build machine** using **docker**.
+
+.. code-block:: bash
+
+    $ docker build --tag o3skim .
+    ...
+    Successfully built 69587025a70a
+    Successfully tagged o3skim:latest
+
+
+If the build process succeded, you should see the image name on the container images list:
+
+.. code-block:: bash
+
+    $ docker images
+    REPOSITORY                         TAG                 IMAGE ID            CREATED              SIZE
+    o3skim                             latest              69587025a70a        xx seconds ago      557MB
+    ...
+

docs/getting_started/cli.rst

+Command Line Interface
+=======================
+
+Finally, run the container. Note the described `data`, `output` and 
+`sources.yaml` have to be provided. Also it is needed to specify the 
+user `application` should run inside the container:
+
+.. code-block:: bash
+
+    $ udocker run \
+      --user=application \
+      --volume=${PWD}/sources.yaml:/app/sources.yaml \
+      --volume=${PWD}/data:/app/data \
+      --volume=${PWD}/output:/app/output \
+      o3skim --verbosity INFO
+    ...
+    executing: main
+    ...
+    2020-08-25 12:42:34,151 - INFO     - Configuration found at: './sources.yaml'
+    2020-08-25 12:42:34,152 - INFO     - Loading data from './data' 
+    2020-08-25 12:42:34,261 - INFO     - Skimming data to './output' 
+
+
+For the main function description and commands help you can call:
+
+.. code-block:: bash
+
+    $ udocker run --user=application o3skim --help
+    ...
+
+

docs/getting_started/deployment.rst

+Deployment
+==================================
+
+To deploy the the application using **udocker** at the **Runtime machine** 
+you need:
+
+ - Input path with data to skim, to be mounter on `/app/data` inside the 
+   container.
+ - Output path for skimmed results, to be mounted on `/app/output` inside
+   the container.
+ - Configuration file with a data structure desctiption at the input path
+   in YAML_ format. This configuration file has to be mounted on 
+   `/app/sources.yaml` inside the container. 
+   See [sources_example.yaml](/sources_example.yaml) for a configuration 
+   example.
+
+.. _YAML: https://yaml.org/
+
+
+Once the requierement are needed, pull the image from the image registry.
+For example, to pull it from the synergy-imk official registry use:
+
+.. code-block:: bash
+
+    $ udocker pull synergyimk/o3skim
+    ...
+    Downloading layer: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
+    ...
+
+
+Once the repository is added and the image downloaded, create the local container: 
+
+.. code-block:: bash
+
+    $ udocker create --name=o3skim synergyimk/o3skim
+    fa42a912-b0d4-3bfb-987f-1c243863802d
+

docs/getting_started/prerequisites.rst

+Prerequisites
+==================================
+
+To run the project as container, you need the following systems and container technologies:
+
+ - **Build machine** with docker_
+ - **Runtime machine** with udocker_
+
+
+.. rubric:: Note udocker_ cannot be used to build containers, only to run them.
+
+.. _docker: https://docs.docker.com/engine/install/
+.. _udocker: https://indigo-dc.gitbook.io/udocker/installation_manual
+

docs/index.rst

+=========================================
+o3skim
+=========================================
+.. rubric:: Data skiming for ozone assessment.
+
+**o3skim** is an open source project and Python package that provides the 
+tools to preprocess, standarise and reduce ozone data from netCDF_ models to
+simplify and speed up ozone data transfer and plot.
+
+.. _netCDF: http://www.unidata.ucar.edu/software/netcdf
+
+Documentation
+-------------
+
+**Getting Started**
+
+* Which :doc:`getting_started/prerequisites` you need to start.
+* How to :doc:`getting_started/build` your o3skim container.
+* How to :doc:`getting_started/deployment` your o3skim container.
+* How to use the o3skim :doc:`getting_started/cli`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Getting Started
+
+   getting_started/prerequisites
+   getting_started/build
+   getting_started/deployment
+   getting_started/cli
+
+**User Guide**
+
+* :doc:`user_guide/source-file`
+* :doc:`user_guide/API-reference`
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   user_guide/source-file
+   user_guide/API-reference
+
+
+**Developer Guide**
+
+* :doc:`dev_guide/local-install`
+* :doc:`dev_guide/tests`
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   dev_guide/local-install
+   dev_guide/tests
+
+
+See also
+--------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+Authors
+-------
+- [@V.Kozlov](https://git.scc.kit.edu/eo9869) - TBD
+- [@T.Kerzenmacher](https://git.scc.kit.edu/px5501) - TBD
+- [@B.Esteban](https://git.scc.kit.edu/zr5094) - TBD
+
+
+Acknowledgements
+----------------
+
+

docs/make.bat

+@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/user_guide/API-reference.rst

+API-reference
+==================================
\ No newline at end of file

docs/user_guide/source-file.rst

+Source file
+==================================
\ No newline at end of file