Merge pull request #343 from clamsproject/develop

releasing 1.2.1

Author: keighrim

.gitignore

@@ -84,3 +84,4 @@ documentation/_build/
 /VERSION
 _issues
 
+documentation/cli_help.rst

documentation/autodoc/mmif.utils.rst

@@ -1,39 +1,49 @@
 mmif.utils package
 ==================
 
-Package containing utility modules for handling different types of source 
-documents, and general implementation of common data structures and 
+Package containing utility modules for handling different types of source
+documents, and general implementation of common data structures and
 algorithms.
 
+Submodules
+----------
+
 ``video_document_helper`` module
-----------------------------------------
+--------------------------------
 
 .. automodule:: mmif.utils.video_document_helper
    :members:
    :undoc-members:
    :show-inheritance:
 
 ``text_document_helper`` module
----------------------------------
+-------------------------------
 
-.. automodule:: mmif.utils.sequence_helper
+.. automodule:: mmif.utils.text_document_helper
    :members:
    :undoc-members:
    :show-inheritance:
 
-``sequence_helper`` module
----------------------------------
+``timeunit_helper`` module
+-------------------------------
 
-.. automodule:: mmif.utils.sequence_helper
+.. automodule:: mmif.utils.timeunit_helper
    :members:
    :undoc-members:
    :show-inheritance:
 
 ``sequence_helper`` module
----------------------------------
+--------------------------
 
 .. automodule:: mmif.utils.sequence_helper
    :members:
    :undoc-members:
    :show-inheritance:
 
+``workflow_helper`` module
+--------------------------
+
+.. automodule:: mmif.utils.workflow_helper
+   :members:
+   :undoc-members:
+   :show-inheritance:

documentation/cli.rst

@@ -0,0 +1,20 @@
+.. _cli:
+
+``mmif`` shell command
+======================
+
+``mmif-python`` comes with a command line interface (CLI) that allows you to handle MMIF files. Many of these commands are designed to handle MMIF files in the context of CLAMS workflows.
+
+The CLI is installed as ``mmif`` shell command. To see the available commands, run
+
+.. code-block:: bash
+
+    mmif --help
+
+.. contents::
+    :local:
+    :backlinks: none
+
+The following documentation is automatically generated from the CLI help messages.
+
+.. include:: cli_help.rst

documentation/conf.py

@@ -5,6 +5,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import datetime
+import textwrap
 
 # -- Path setup --------------------------------------------------------------
 
@@ -110,4 +111,40 @@ def linkcode_resolve(domain, info):
 # 1. sphinx-mv/main.py know current version of the library by git tag, 
 #    but conf.py has no way to know that... 
 # 2. target-versions.csv file can be read once and used in the for loop 
-#    in sphinx-mv/main.py, but here it should be read in for each `docs` bulid. 
+# ... (previous content)
+
+def generate_cli_rst(app):
+    import mmif
+    from mmif import prep_argparser_and_subcmds, find_all_modules
+    
+    # Generate main help
+    os.environ['COLUMNS'] = '100'
+    parser, subparsers = prep_argparser_and_subcmds()
+    help_text = parser.format_help()
+    
+    content = []
+    
+    content.append('Main Command\n')
+    content.append('------------\n\n')
+    content.append('.. code-block:: text\n\n')
+    content.append(textwrap.indent(help_text, '    '))
+    content.append('\n\n')
+    
+    # Generate subcommand help
+    for cli_module in find_all_modules('mmif.utils.cli'):
+        cli_module_name = cli_module.__name__.rsplit('.')[-1]
+        subparser = cli_module.prep_argparser(prog=f'mmif {cli_module_name}')
+        sub_help = subparser.format_help()
+        
+        content.append(f'{cli_module_name}\n')
+        content.append('-' * len(cli_module_name) + '\n\n')
+        content.append('.. code-block:: text\n\n')
+        content.append(textwrap.indent(sub_help, '    '))
+        content.append('\n\n')
+
+    with open(proj_root_dir / 'documentation' / 'cli_help.rst', 'w') as f:
+        f.write(''.join(content))
+
+
+def setup(app):
+    app.connect('builder-inited', generate_cli_rst)

documentation/index.rst

@@ -8,6 +8,7 @@ Welcome to mmif-python's documentation!
   :caption: Contents
 
   introduction
+  cli
   plugins
   target-versions
 

documentation/introduction.rst

@@ -87,3 +87,9 @@ To get subcomponents, you can use various getters implemented in subclasses. For
 
 For a full list of available helper methods, please refer to :ref:`the API documentation <apidoc>`. 
 
+MMIF usage in CLAMS Workflows
+-----------------------------
+
+In the context of CLAMS, a **Workflow** refers to the sequence of CLAMS applications that have been executed to generate the views and annotations within a MMIF file.
+
+When using the ``mmif-python`` SDK, a unique identifier for a workflow (``workflowId``) is calculated based on the applications involved. This identifier is constructed by concatenating the application name, version, and a hash of the runtime parameters for each step in the sequence. This ensures that the identifier uniquely represents not just the apps used, but their specific configurations, aiding in reproducibility.

mmif/serialize/annotation.py

@@ -2,7 +2,7 @@
 The :mod:`annotation` module contains the classes used to represent a
 MMIF annotation as a live Python object.
 
-In MMIF, annotations are created by apps in a pipeline as a part
+In MMIF, annotations are created by apps in a workflow as a part
 of a view. For documentation on how views are represented, see
 :mod:`mmif.serialize.view`.
 """

mmif/serialize/mmif.py

@@ -635,7 +635,7 @@ def get_alignments(self, at_type1: Union[str, ThingTypesBase], at_type2: Union[s
     def get_views_for_document(self, doc_id: str) -> List[View]:
         """
         Returns the list of all views that have annotations anchored on a particular document.
-        Note that when the document is inside a view (generated during the pipeline's running),
+        Note that when the document is inside a view (generated during the workflow's running),
         doc_id must be prefixed with the view_id.
         """
         views = []

mmif/serialize/view.py

@@ -2,7 +2,7 @@
 The :mod:`view` module contains the classes used to represent a MMIF view
 as a live Python object.
 
-In MMIF, views are created by apps in a pipeline that are annotating
+In MMIF, views are created by apps in a workflow that are annotating
 data that was previously present in the MMIF file.
 
 The :class:`View` class is a high-level container that provides convenient