update docs, addressed some errors related to sphinx-argparse extension

dedop/cli/main.py

@@ -13,15 +13,13 @@
 import subprocess
 import sys
 
-from dedop.model.processor import BaseProcessor, ProcessorException
-from dedop.proc.sar import L1BProcessor
-from dedop.ui.workspace_manager import WorkspaceError, WorkspaceManager
+from cate.util.cli import run_main, Command, SubCommandCommand, CommandError
+
+from dedop.ui.exception import WorkspaceError
 from dedop.util.config import DEFAULT_CONFIG_FILE, get_config_path, get_config_value
 from dedop.util.monitor import Monitor
 from dedop.version import __version__
 
-from cate.util.cli import run_main, Command, SubCommandCommand, CommandError
-
 _DEFAULT_SUFFIX = '_1'
 
 _DEFAULT_CONFIG_NAME = 'default'
@@ -60,26 +58,6 @@
 _PROCESSOR_FACTORY = None
 
 
-def new_l1b_processor(name: str,
-                      cnf_file: str = None,
-                      cst_file: str = None,
-                      chd_file: str = None,
-                      output_dir: str = '.',
-                      skip_l1bs: bool = True) -> BaseProcessor:
-    """
-    Create a new L1B processor instance.
-
-    :param name: the processor "run" name
-    :param cnf_file: configuration definition file
-    :param cst_file: constants definition file
-    :param chd_file: characterisation definition file
-    :param output_dir: the output directory for L1B, L1B-S, and log-files, etc.
-    :param skip_l1bs: whether to skip L1B-S output
-    :return: an object of type :py_class:`BaseProcessor`
-    """
-    return L1BProcessor(name, cnf_file, cst_file, chd_file, output_dir, skip_l1bs)
-
-
 def _input(prompt, default=None):
     answer = input(prompt).strip()
     return answer if answer else default
@@ -175,6 +153,8 @@ def configure_parser(cls, parser: argparse.ArgumentParser):
                             help='Run all DDP configurations in workspace. Cannot be used with option -c')
 
     def execute(self, command_args):
+        from dedop.model.exception import ProcessorException
+
         try:
             if command_args.all_configs and command_args.config_name:
                 raise CommandError('option -a cannot be used with option -c"')
@@ -652,6 +632,7 @@ def create_config(cls, workspace_name, config_name, exist_ok=True, cryosat=False
         """
         Create a new configuration *config_name* in workspace *workspace_name*.
 
+        :param cryosat: if true, create a new configuration based on Cryosat-2 FBR config template
         :param workspace_name: Workspace name
         :param config_name: Configuration name
         :param exist_ok: if True, *config_name* may already exist
@@ -1274,6 +1255,29 @@ def _make_dedop_parser():
 
 
 def main(args=None, workspace_manager=None, processor_factory=None) -> int:
+    from dedop.model.processor import BaseProcessor
+    from dedop.proc.sar import L1BProcessor
+    from dedop.ui.workspace_manager import WorkspaceManager
+
+    def new_l1b_processor(name: str,
+                          cnf_file: str = None,
+                          cst_file: str = None,
+                          chd_file: str = None,
+                          output_dir: str = '.',
+                          skip_l1bs: bool = True) -> BaseProcessor:
+        """
+        Create a new L1B processor instance.
+
+        :param name: the processor "run" name
+        :param cnf_file: configuration definition file
+        :param cst_file: constants definition file
+        :param chd_file: characterisation definition file
+        :param output_dir: the output directory for L1B, L1B-S, and log-files, etc.
+        :param skip_l1bs: whether to skip L1B-S output
+        :return: an object of type :py_class:`BaseProcessor`
+        """
+        return L1BProcessor(name, cnf_file, cst_file, chd_file, output_dir, skip_l1bs)
+
     if not processor_factory:
         processor_factory = get_config_value('processor_factory')
 

dedop/model/exception.py

@@ -0,0 +1,17 @@
+
+
+class ProcessorException(Exception):
+    """
+    An exception type raised by :py:class:`BaseProcessor` and its derived classes.
+    :param message: The exception message
+    :param cause: Another error/exception that caused this one to be raised.
+    """
+
+    def __init__(self, message, cause=None):
+        if not message:
+            raise ValueError('message must be given')
+        self.message = message
+        self.cause = cause
+
+    def __str__(self):
+        return str(self.message)

dedop/model/processor.py

@@ -5,23 +5,6 @@
 from dedop.util.monitor import Monitor
 
 
-class ProcessorException(Exception):
-    """
-    An exception type raised by :py:class:`BaseProcessor` and its derived classes.
-    :param message: The exception message
-    :param cause: Another error/exception that caused this one to be raised.
-    """
-
-    def __init__(self, message, cause=None):
-        if not message:
-            raise ValueError('message must be given')
-        self.message = message
-        self.cause = cause
-
-    def __str__(self):
-        return str(self.message)
-
-
 class BaseProcessor(metaclass=ABCMeta):
     """
     Defines a common interface for all processor objects.

dedop/ui/exception.py

@@ -0,0 +1,7 @@
+
+class WorkspaceError(Exception):
+    def __init__(self, message):
+        self.message = message
+
+    def __str__(self):
+        return self.message

dedop/ui/workspace_manager.py

@@ -11,6 +11,7 @@
 from typing import List
 
 from dedop.ui.workspace import Workspace
+from dedop.ui.exception import WorkspaceError
 from dedop.util.config import get_config_value
 
 _DEFAULT_CONFIG_PACKAGE_NAME = 'dedop.ui.data.config'
@@ -26,14 +27,6 @@
 DEFAULT_TEMP_DIR = os.path.expanduser(os.path.join('~', '.dedop', 'temp'))
 
 
-class WorkspaceError(Exception):
-    def __init__(self, message):
-        self.message = message
-
-    def __str__(self):
-        return self.message
-
-
 def _readline(file_path: str) -> str or None:
     if os.path.exists(file_path) and os.path.isfile(file_path):
         try:

docs/conf.py

@@ -22,11 +22,11 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
 
-# packages thare are difficult to import, becuase the collide with pillow==3.0.0 requirement by rtd
+# packages thare are difficult to import, because the collide with pillow==3.0.0 requirement by rtd
 # http://blog.rtwilson.com/how-to-make-your-sphinx-documentation-compile-with-readthedocs-when-youre-using-numpy-and-scipy/
 import mock
 
-MOCK_MODULES = ['numexpr']
+MOCK_MODULES = ['numexpr', 'cate', 'numpy', 'scipy', 'netCDF4', 'cate-util']
 for mod_name in MOCK_MODULES:
     sys.modules[mod_name] = mock.Mock()
 
@@ -47,6 +47,7 @@
     'sphinx.ext.imgmath',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinxarg.ext'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 |DeDop3| - a User Configurable Tool for Processing Delay Doppler Altimeter Data
-=============================================================================
+================================================================================
 
 .. figure:: _static/figures/dedop-studio-frontpage.png
    :scale: 50%

docs/user_manual/um_setup.rst

@@ -112,8 +112,8 @@ The following software needs to be installed on your machine before you can star
     - nodejs v6.9.1
     - npm v3.10.8 (comes with nodejs)
 
-Go to `here <https://nodejs.org/en/download/releases/>`_ for downloading nodejs and go to
-`this page <https://nodejs.org/en/download/package-manager/>`_ for the installation guide.
+Go to `here <https://nodejs.org/en/download/releases/>` for downloading nodejs and go to
+`this page <https://nodejs.org/en/download/package-manager/>` for the installation guide.
 
 ---------------
 How-to-install

docs/user_manual/um_shell.rst

@@ -5,8 +5,19 @@ DeDop Shell
 Overview
 ========
 
-The DeDop Shell comprises a single command-line executable, which is called ``dedop`` and is available after installing
-the DeDop Shell on your computer. See section :doc:`um_setup` for more information on how to initialize DeDop Shell.
+DeDop Shell comprises a single command-line executable, which is called ``dedop`` and is available after installing
+the DeDop Shell on your computer. With this tool, users can have a complete interaction with the input data, processor,
+configuration, and finally the output products. If you have not done so, see section :doc:`um_setup` to install and
+initialize DeDop Shell.
+
+In this section, you will find a complete manual on how to use DeDop Shell. This can be sub-divided into the following
+parts:
+
+- :ref:`Workspace Management <workspace_manag>`
+- :ref:`Source File Management <source_file_manag>`
+- :ref:`Processor Configuration Management <config_manag>`
+- :ref:`Running the Processor <run_proc>`
+- :ref:`Analyse the Results <analyse_results>`
 
 
 .. _workspace_manag:
@@ -114,8 +125,8 @@ To list available workspaces, run the following command::
 
 .. _source_file_manag:
 
-L1A Source File Management
-==========================
+Source File Management
+======================
 
 After creating a workspace, the next step is to manage the L1A source files.
 
@@ -127,7 +138,8 @@ To add a new L1A file(s) into this workspace, run the following command::
    $ dedop i add /path/to/file1 /path/to/file2 /path/to/file3
 
 What this command does is copying those files into the current workspace directory. When successful, those files will be
-located inside ``inputs`` directory under the current workspace directory.
+located inside ``inputs`` directory under the current workspace directory. Every workspace will have its own ``inputs``
+directory, which in the end can be used as a source file for running multiple processes with different configurations.
 
 Remove L1A source file
 -----------------------
@@ -372,10 +384,10 @@ the outputs, the flag ``--output DIR`` can be used.
 When the flag ``--skip-l1bs`` is added to the command above, the process will generate only L1B files.
 
 
-.. _analyse_l1b:
+.. _analyse_results:
 
-Analysing L1B Results
-=====================
+Analyse the Results
+====================
 
 After the processing has been finished, we can now compare the L1B outputs in an interactive Jupyter Notebook::
 
@@ -449,4 +461,4 @@ The following examples shall help you understand the basic concepts behind the v
 .. argparse::
    :module: dedop.cli.main
    :func: _make_dedop_parser
-   :prog: dedop
+   :prog: dmkae edop

docs/user_manual/um_studio.rst

@@ -145,6 +145,6 @@ on which actions are available, depending on how many files are selected. If onl
 button on **Analysis Configuration** panel is enabled. When two files are selected, the ``Compare`` button is enabled.
 Clicking one of these buttons will trigger a creation of a Jupyter notebook suitable for inspecting or comparing the
 file(s) that have been selected, and to start a local instance of Jupyter notebook server. This behavior is consistent
-with DeDop Shell command :ref:`dedop output compare/inspect <analyse_l1b>`. The dropdown list at the bottom of
+with DeDop Shell command :ref:`dedop output compare/inspect <analyse_results>`. The dropdown list at the bottom of
 **Analysis Configuration** is used to select a notebook file that has been previously created through ``Inspect`` and
 ``Compare`` buttons.

docs/user_manual/um_ws_and_config_concept.rst

@@ -40,11 +40,13 @@ Configuration
 ==============
 
 **DeDop configuration** refers to a set of configurations (Configuration, Characterization, Constants), which in the file
-system are stored as CNF.json, CHD.json, and CST.json. Most of the time, users will need to modify only the **Configuration**.
+system are stored as CNF.json, CHD.json, and CST.json. Most of the time, users will need to modify only the **Configuration**
+(CNF.json).
 A configuration is represented by a directory with a name of the configuration name and is located under ``configs``
 directory inside a workspace directory. It is possible to have multiple configurations under each workspace and it is
-recommended to have a new configuration for different set of configuration values. This way, an output can be easily reproduced
-if needed in the future.
+recommended to have a new configuration for different set of configuration values because in the end the generated output
+products have a one-to-one relationship with the configuration. This enables a particular output to be easily reproduced
+in the future, if required.
 
 As in ``workspaces`` directory, there is a ``.current`` file inside ``configs`` directory. It works following exactly the same
 concept: this file has the information on what is the current configuration. In the case of no current configuration,

readthedocs-env.yml

@@ -3,15 +3,14 @@ channels:
     - conda-forge
     - defaults
 dependencies:
-      # rdt requires "sphinx_rtd_theme ==0.1.7" which is not available for python 3.6 yet.
-  - python=3.5*
+  - python=3.6*
   #
   # for testing
   #
   - pytest
   - pytest-cov
   - tornado
-  # v 0.2.0 of sphinx-argparse needs a greater commonmark-parser version than rtd
-  - sphinx-argparse ==0.1.17
+  - mock
+  - sphinx-argparse
   - pip:
     - sphinx_autodoc_annotation