user manual for dedop run and output

dedop/cli/main.py

@@ -38,7 +38,7 @@
 CLI_DESCRIPTION = 'Delay Doppler Altimeter Data (DeDop) command-line interface'
 
 _LICENSE_INFO_PATH = os.path.join(os.path.dirname(__file__), '..', '..', 'LICENSE')
-_DOCS_URL = 'http://dedop.readthedocs.io/en/latest/'
+_DOCS_URL = 'http://dedop-core.readthedocs.io/en/latest/'
 _LICENSE = """
 {dedop} - ESA DeDop Shell, copyright (C) 2016 by the DeDop team and contributors
 

docs/conf.py

@@ -74,9 +74,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '1.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1a1'
+release = '1.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/manual.rst

@@ -29,12 +29,12 @@ be triggered by running ``dedop input add some/path/to/your/L1A.nc`` or ``dedop
 
 Another (more recommended) way to add a new workspace is by running the following command::
 
-   dedop w add workspace_name
+   $ dedop w add workspace_name
 
 Upon successful operation, the following responses shall be returned::
 
-   created workspace "workspace_name"
-   current workspace is "workspace_name"
+   $ created workspace "workspace_name"
+   $ current workspace is "workspace_name"
 
 This means that the new workspace has been successfully created and made the current workspace, which means that, unless
 explicitly changed, whatever operations being performed after this will happen inside this workspace.
@@ -44,8 +44,8 @@ Remove a workspace
 
 To remove a workspace, run one of the following commands::
 
-   dedop w remove                   # CASE 1
-   dedop w remove workspace_name    # CASE 2
+   $ dedop w remove                   # CASE 1
+   $ dedop w remove workspace_name    # CASE 2
 
 In both cases, a confirmation prompt will appear to really ensure that this action is intentional. To disable this prompt,
 use the optional argument ``--yes`` (eg. ``dedop w remove --yes``).
@@ -63,9 +63,9 @@ Copy a workspace
 
 To copy a workspace, run one of the following commands::
 
-   dedop w copy                                       # CASE 1
-   dedop w copy workspace_to_be_copied                # CASE 2
-   dedop w copy workspace_to_be_copied new_workspace  # CASE 3
+   $ dedop w copy                                       # CASE 1
+   $ dedop w copy workspace_to_be_copied                # CASE 2
+   $ dedop w copy workspace_to_be_copied new_workspace  # CASE 3
 
 In **CASE 1**, without specifying which workspace to be copied, it will default to the current workspace. The new workspace
 name is also not specified, so in this case a new name with the format of ``current_workspace_name + _ + unique_number``
@@ -87,8 +87,8 @@ Rename a workspace
 
 To rename a workspace, run one of the following commands::
 
-   dedop w rename new_workspace_name                           # CASE 1
-   dedop w rename workspace_to_be_renamed new_workspace_name   # CASE 2
+   $ dedop w rename new_workspace_name                           # CASE 1
+   $ dedop w rename workspace_to_be_renamed new_workspace_name   # CASE 2
 
 In **CASE 1**, the current workspace will be renamed to ``new_workspace_name``. The current workspace will be automatically
 changed after the renaming.
@@ -102,7 +102,7 @@ Get current workspace
 
 It is sometimes useful to know in which workspace we are working on at the moment. To get that information, run the following::
 
-   dedop w current
+   $ dedop w current
 
 If there is a current workspace, the name of the current workspace will be returned. Otherwise, ``no current workspace``
 will be returned.
@@ -130,7 +130,7 @@ Add new L1A source file
 
 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
+   $ 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.
@@ -140,10 +140,10 @@ Remove L1A source file
 
 To remove the previously-added L1A file(s), run one of the following commands::
 
-   dedop i remove                                           # CASE 1
-   dedop i remove file_name1 file_name2                     # CASE 2
-   dedop i remove -w workspace_name                         # CASE 3
-   dedop i remove -w workspace_name file_name1 file_name2   # CASE 4
+   $ dedop i remove                                           # CASE 1
+   $ dedop i remove file_name1 file_name2                     # CASE 2
+   $ dedop i remove -w workspace_name                         # CASE 3
+   $ dedop i remove -w workspace_name file_name1 file_name2   # CASE 4
 
 In all cases, a confirmation prompt will appear to really ensure that this action is intentional. To disable this prompt,
 use the optional argument ``--quiet`` (eg. ``dedop i remove --quiet``).
@@ -163,9 +163,9 @@ List all L1A source files
 
 To list all source files that have been added, run one of the following commands::
 
-   dedop i list                     # CASE 1
-   dedop i list -w other_workspace  # CASE 2
-   dedop i list L1A*                # CASE 3
+   $ dedop i list                     # CASE 1
+   $ dedop i list -w other_workspace  # CASE 2
+   $ dedop i list L1A*                # CASE 3
 
 In **CASE 1**, the tool will return a list of all source files in the current workspace.
 
@@ -187,9 +187,9 @@ Add a new configuration
 
 To add a new configuration, run one of the following commands::
 
-   dedop c add new_config_name                     # CASE 1
-   dedop c add -w other_workspace new_config_name  # CASE 2
-   dedop c add --cryosat-adapted new_config_name   # CASE 3
+   $ dedop c add new_config_name                     # CASE 1
+   $ dedop c add -w other_workspace new_config_name  # CASE 2
+   $ dedop c add --cryosat-adapted new_config_name   # CASE 3
 
 In all cases, a new folder named ``new_config_name`` is created under a workspace and it consists of three default configuration
 files ``CHD.json``, ``CNF.json``, and ``CST.json``. The generated configurations are by default for ``Sentinel-3`` processing
@@ -206,9 +206,9 @@ Remove a configuration
 
 To remove a configuration, run one of the following commands::
 
-   dedop c remove                                  # CASE 1
-   dedop c remove config_name                      # CASE 2
-   dedop c remove -w other_workspace config_name   # CASE 3
+   $ dedop c remove                                  # CASE 1
+   $ dedop c remove config_name                      # CASE 2
+   $ dedop c remove -w other_workspace config_name   # CASE 3
 
 In all cases, a confirmation prompt will appear to really ensure that this action is intentional. To disable this prompt,
 use the optional argument ``--yes`` (eg. ``dedop c remove --yes``). Removing a configuration means deleting a configuration
@@ -229,9 +229,9 @@ Modify a configuration
 
 To modify a configuration, run one of the following commands::
 
-   dedop c edit                                 # CASE 1
-   dedop c edit config_name                     # CASE 2
-   dedop c edit -w other_workspace config_name  # CASE 3
+   $ dedop c edit                                 # CASE 1
+   $ dedop c edit config_name                     # CASE 2
+   $ dedop c edit -w other_workspace config_name  # CASE 3
 
 In all cases, it will launch a text editor and open all three configuration files. The text editor to be launched is OS-dependent
 and it is configurable on the :ref:`Tool Configuration <tool_config>` with the key name :ref:`launch_editor_command <tool_config_parameters>`.
@@ -251,10 +251,10 @@ Copy a configuration
 
 To copy a configuration, run one of the following commands::
 
-   dedop c copy                                                               # CASE 1
-   dedop c copy config_name_to_be_copied                                      # CASE 2
-   dedop c copy config_name_to_be_copied new_config_name                      # CASE 3
-   dedop c copy -w other_workspace config_name_to_be_copied new_config_name   # CASE 4
+   $ dedop c copy                                                               # CASE 1
+   $ dedop c copy config_name_to_be_copied                                      # CASE 2
+   $ dedop c copy config_name_to_be_copied new_config_name                      # CASE 3
+   $ dedop c copy -w other_workspace config_name_to_be_copied new_config_name   # CASE 4
 
 In **CASE 1**, neither the configuration to be copied nor the new configuration name is specified, so in this case a new
 name with the format of ``current_config_name + _copy_ + unique_number`` is created. The unique number will be incremented
@@ -278,9 +278,9 @@ Rename a configuration
 
 To rename a configuration, run one of the following commands::
 
-   dedop c rename new_config_name                                          # CASE 1
-   dedop c rename config_to_be_renamed new_config_name                     # CASE 2
-   dedop c rename -w other_workspace config_to_be_renamed new_config_name  # CASE 3
+   $ dedop c rename new_config_name                                          # CASE 1
+   $ dedop c rename config_to_be_renamed new_config_name                     # CASE 2
+   $ dedop c rename -w other_workspace config_to_be_renamed new_config_name  # CASE 3
 
 In **CASE 1**, the current config name will be renamed to ``new_config_name``. The current configuration will also be
 changed to ``new_config_name``.
@@ -297,9 +297,9 @@ Show configuration info
 To display information about the configuration such as current configuration path, list of files, as well as the file sizes,
 run the following command::
 
-   dedop c info                                 # CASE 1
-   dedop c info other_config                    # CASE 2
-   dedop c info -w other_workspace config_name  # CASE 3
+   $ dedop c info                                 # CASE 1
+   $ dedop c info other_config                    # CASE 2
+   $ dedop c info -w other_workspace config_name  # CASE 3
 
 In **CASE 1**, information for the current configuration in the current workspace will be displayed.
 
@@ -314,7 +314,7 @@ Get current configuration
 
 To get the current configuration name, run the following::
 
-   dedop c current
+   $ dedop c current
 
 If there is a current configuration, the name of the current configuration will be returned. Otherwise,
 ``no current DDP configuration`` will be returned.
@@ -329,7 +329,7 @@ List configurations
 
 To list available configurations, run one of the following commands::
 
-   dedop c list
+   $ dedop c list
 
 As before, to list available configurations in the other workspace, just add ``-w other_workspace_name`` in the command.
 
@@ -341,7 +341,7 @@ Upgrade configurations
 A new version of DeDop Core sometimes comes with new versions of configuration files. In order to update your configurations,
 run the following command::
 
-   dedop c upgrade
+   $ dedop c upgrade
 
 Failure to use the latest version of configurations may result in processing errors.
 
@@ -352,7 +352,7 @@ Show configuration version
 
 To display the current configuration version, run the following command::
 
-   dedop c version
+   $ dedop c version
 
 ``version`` has an alias ``v``.
 
@@ -361,21 +361,36 @@ To display the current configuration version, run the following command::
 Running the Processor
 =====================
 
-TODO
+Once the L1A source files have been added and configurations have been created, it is time to run the processing. To
+do that, use the following command::
+
+   $ dedop run
+
+This command calls a processor to process L1A files to L1B (and possible L1BS). More information on how the processor
+works, go to :ref:`here <processor_info_not_yet_exists>`. By default, the command above will process every single L1A files
+inside the ``inputs`` directory under the current workspace, unless ``--inputs [L1A_FILE [L1A_FILE ...]]`` flag is specified.
+
+The default behaviour is that the processor will run based on the current configuration. However, when ``--all-configs``
+flag is set, it will process the same input files with all available configurations in the current workspace. The output
+products will be located inside ``outputs`` directory under each configuration directory. To specify other locations for
+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:
 
 Analysing L1B Results
 =====================
 
-TODO
-
-.. _command_ref:
+After the processing has been finished, we can now compare the L1B outputs in an interactive Jupyter Notebook::
 
-Command Reference
-=================
+    $ dedop output compare -C default L1B_myconf.nc L1B_default.nc
 
-TODO
+When you pass just file *names* to the ``dedop output compare`` command, DeDop must know to which configurations they
+refer to. The first filename corresponds to the *current* DDP configuration or the one given by the ``-c`` option.
+The second filename corresponds to a DDP configuration given by the ``-C`` (upper case!) option.
+You can also pass file *paths* to the ``dedop output compare`` command in which case the configuration names are ignored.
 
 .. _tool_config:
 
@@ -430,10 +445,10 @@ Parameter name                       Description
 ===================================  =====================================================   ===========================
 
 
-.. _cli_examples:
+.. _command_ref:
 
-Examples
-========
+Command Reference
+=================
 
 The following examples shall help you understand the basic concepts behind the various ``dedop`` commands.