Commit 34819dcf authored by BorjaEst's avatar BorjaEst
Browse files

Merge branch '24-generate-documentation' into dev

parents f104410e 073d29a0
......@@ -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>
-
......
### Documentation builds
_build
_static
_templates
# 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)
# 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
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++:
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
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
...
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
...
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
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
=========================================
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
----------------
@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
API-reference
==================================
\ No newline at end of file
Source file
==================================
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment