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]( - TBD
- [@T.Kerzenmacher]( - TBD
- [@B.steban]( - TBD
- [@B.Esteban]( - TBD
# Acknowledgements <a name = "acknowledgement"></a>
### Documentation builds
# Minimal makefile for Sphinx documentation
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXBUILD ?= sphinx-build
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
.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
# 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:
# -- 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 = [
# 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:
.. _pip:
.. _gcc:
.. _g++:
Tests should run using tox_
.. _tox:
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
Download the repository at the **Build machine** using git.
.. code-block:: bash
$ git clone
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
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
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
- 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
.. _YAML:
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
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:
.. _udocker:
.. 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:
**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
:caption: Getting Started
**User Guide**
* :doc:`user_guide/source-file`
* :doc:`user_guide/API-reference`
.. toctree::
:maxdepth: 1
:caption: Contents:
**Developer Guide**
* :doc:`dev_guide/local-install`
* :doc:`dev_guide/tests`
.. toctree::
:maxdepth: 1
:caption: Contents:
See also
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
- [@V.Kozlov]( - TBD
- [@T.Kerzenmacher]( - TBD
- [@B.Esteban]( - TBD
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
set BUILDDIR=_build
if "%1" == "" goto help
if errorlevel 9009 (
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.If you don't have Sphinx installed, grab it from
exit /b 1
goto end
\ 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