Add detailed docstrings and usage examples to CLI command functions (#…

…1427)

* Merge sample command with the example command (#1422)

* Merge sample command with the example command

* Fix example command usage

* Generalize Standard Run  (#1411)

* Modify header calculation to choose from predefined example output file or standard example output file

* Remove the readiness function from SCRA because it is redundant, since those checks are also performed by the amenable function

* Remove unused method

* Make csv serialization work for any kind of model api response

* Remove the standard flag from the CLI since it is now the default run

* Update tests

* Unnecessary files removed

* Unnecessary files removed

* Unnecessary files removed

* Unnecessary files removed

* Unnecessary files removed

* Add detailed docstring and usage examples to command functions and modules

---------

Co-authored-by: Dhanshree Arora <DhanshreeA@users.noreply.github.com>

ersilia/cli/cmd.py

@@ -2,6 +2,10 @@
 
 
 class Command(object):
+    """
+    Command class to dynamically import and execute CLI commands.
+    """
+
     def __init__(self):
         pass
 

ersilia/cli/commands/catalog.py

@@ -6,8 +6,26 @@
 
 
 def catalog_cmd():
-    """Creates catalog command"""
+    """
+    Creates the catalog command for the CLI.
 
+    This command allows users to list a catalog of models available either locally or in the model hub.
+    It provides options to display the catalog in various formats(such as tables or json), show more detailed information,
+    and view model cards for specific models.
+
+    Returns
+    -------
+    function
+        The catalog command function to be used by the CLI and for testing in the pytest.
+
+    Examples
+    --------
+    List models available in the local computer and show more detailed information:
+    $ ersilia catalog --local --more
+
+    Display model card for a specific model ID and show catalog in table format:
+    $ ersilia catalog --card <model_id> --as-table
+    """
     # Example usage: ersilia catalog
     @ersilia_cli.command(help="List a catalog of models")
     @click.option(

ersilia/cli/commands/close.py

@@ -7,6 +7,21 @@
 
 
 def close_cmd():
+    """
+    Closes the current session.
+
+    This command allows users to close the current session and clean up any resources.
+
+    Returns
+    -------
+    function
+        The close command function to be used by the CLI and for testing in the pytest.
+
+    Examples
+    --------
+    Close the current session:
+    $ ersilia close
+    """
     # Example usage: ersilia close {MODEL}
     @ersilia_cli.command(short_help="Close model", help="Close model")
     def close():

ersilia/cli/commands/delete.py

@@ -11,7 +11,24 @@
 
 
 def delete_cmd():
-    """Create delete command"""
+    """
+    Deletes a specified model.
+
+    This command allows users to delete a specified model from the local storage.
+
+    Returns
+    -------
+    function
+        The delete command function to be used by the CLI and for testing in the pytest.
+
+    Examples
+    --------
+    Delete a specific model:
+    $ ersilia delete <model_id>
+
+    Delete all models:
+    $ ersilia delete --all
+    """
 
     def _delete_model_by_id(model_id):
         md = ModelFullDeleter()

ersilia/cli/commands/example.py

@@ -10,20 +10,34 @@
 
 
 def example_cmd():
-    """Create example command"""
+    """
+    Generates example files such as compound SMILES that serve as input for models.
 
-    # Example usage: ersilia example {MODEL} -n 10 [--file_name {FILE_NAME} --simple/--complete]
+    This command allows users to generate example files that can be used as input for models in the CLI.
+
+    Returns
+    -------
+    function
+        The example command function to be used by the CLI.
+
+    Examples
+    --------
+    Generate sample inputs for a model:
+    $ ersilia example {MODEL} -n 10 [--file_name {FILE_NAME} --simple/--complete]
+    """
     @ersilia_cli.group(
-        short_help="Generate sample of Ersilia models or model inputs",
-        help="""This command can sample both ersilia models, or inputs for a given or currently running model.\n
-For the model input, the number of examples can be specified, as well as a file name.\n
-Simple inputs only contain the essential information, while complete inputs contain key and other fields, potentially.\n
-For ersilia models, only model identifiers are returned for a given sample size.
-""",
+        short_help="Generate samples of Ersilia models or model inputs",
+        help="""
+        This command allows users to generate samples of Ersilia models or inputs for a specified or currently running model.
+        For model inputs, users can specify the number of examples, as well as an optional file name.
+        Simple inputs contain only essential information, while complete inputs may include additional fields.
+        For Ersilia models, only model identifiers are returned for a given sample size.
+        """
     )
     def example():
         pass
 
+
     @example.command()
     @click.argument("model", required=False, default=None, type=click.STRING)
     @click.option("--n_samples", "-n", default=5, type=click.INT)
@@ -36,15 +50,6 @@ def inputs(model, n_samples, file_name, simple, predefined):
         else:
             session = Session(config_json=None)
             model_id = session.current_model_id()
-            if model_id is None:
-                click.echo(
-                    click.style(
-                        "Error: No model id given and no model found running in this shell.",
-                        fg="red",
-                    ),
-                    err=True,
-                )
-                return
         eg = ExampleGenerator(model_id=model_id)
         if file_name is None:
             echo(
@@ -56,6 +61,7 @@ def inputs(model, n_samples, file_name, simple, predefined):
         else:
             eg.example(n_samples, file_name, simple, try_predefined=predefined)
 
+
     @example.command()
     @click.option("--n_samples", "-n", default=5, type=click.INT)
     @click.option("--file_name", "-f", default=None, type=click.STRING)
@@ -65,4 +71,4 @@ def models(n_samples, file_name):
         if file_name is None:
             echo(json.dumps(sampler.sample(n_samples), indent=4))
         else:
-            sampler.sample(n_samples, file_name)
+            sampler.sample(n_samples, file_name)

ersilia/cli/commands/fetch.py

@@ -10,8 +10,24 @@
 
 
 def fetch_cmd():
-    """Create fetch commmand"""
+    """
+    Fetches a specified model.
 
+    This command allows users to fetch a specified model from the model hub (dockerhub, repo, s3 etc...).
+
+    Returns
+    -------
+    function
+        The fetch command function to be used by the CLI and for testing in the pytest.
+
+    Examples
+    --------
+    Fetch a model by its ID:
+    $ ersilia fetch <model_id> [auto model source decider] or ersilia fetch <model_id> --from_github/--from_dockerhub
+
+    Fetch a model from a local directory:
+    $ ersilia fetch <model_id> --from_dir <path>
+    """
     def _fetch(mf, model_id):
         res = asyncio.run(mf.fetch(model_id))
         return res

ersilia/cli/commands/info.py

@@ -8,7 +8,21 @@
 
 
 def info_cmd():
-    # Example usage: ersilia info {MODEL}
+    """
+    Provides information about a specified model.
+
+    This command allows users to get detailed information about a current active session.
+
+    Returns
+    -------
+    function
+        The info command function to be used by the CLI.
+
+    Examples
+    --------
+    Get information about active session as json:
+    $ ersilia info  --as_json
+    """
     @ersilia_cli.command(
         short_help="Get model information", help="Get model information"
     )

ersilia/cli/commands/publish.py

@@ -8,8 +8,24 @@
 
 
 def publish_cmd():
-    """Create publish commmand"""
+    """
+    Publishes a specified model.
 
+    This command allows users to publish a specified model to the model hub.
+
+    Returns
+    -------
+    function
+        The publish command function to be used by the CLI.
+
+    Examples
+    --------
+    Publish a model by its ID:
+    $ ersilia publish create <model_id>
+
+    Rebase a model:
+    $ ersilia publish rebase <model_id>
+    """
     def _publish(mf, model_id):
         mf.publish(model_id)
 

ersilia/cli/commands/run.py

@@ -12,8 +12,24 @@
 
 
 def run_cmd():
-    """Create run command"""
+    """
+    Runs a specified model.
 
+    This command allows users to run a specified model with given inputs.
+
+    Returns
+    -------
+    function
+        The run command function to be used by the CLI and for testing in the pytest.
+
+    Examples
+    --------
+    Run a model by its ID with input data:
+    $ ersilia run -i <input_data> --table
+
+    Run a model with batch size:
+    $ ersilia run -i <input_data> -b 50
+    """
     # Example usage: ersilia run -i {INPUT} [-o {OUTPUT} -b {BATCH_SIZE}]
     @ersilia_cli.command(short_help="Run a served model", help="Run a served model")
     @click.option("-i", "--input", "input", required=True, type=click.STRING)

ersilia/cli/commands/serve.py

@@ -8,8 +8,24 @@
 
 
 def serve_cmd():
-    """Creates serve command"""
+    """
+    Serves a specified model.
 
+    This command allows users to serve a specified model as an API.
+
+    Returns
+    -------
+    function
+        The serve command function to be used by the CLI and for testing in the pytest.
+
+    Examples
+    --------
+    Serve a model by its ID:
+    $ ersilia serve <model_id> --port 8080
+
+    Serve a model and track the session:
+    $ ersilia serve <model_id> --track
+    """
     # Example usage: ersilia serve {MODEL}
     @ersilia_cli.command(short_help="Serve model", help="Serve model")
     @click.argument("model", type=click.STRING)

ersilia/cli/commands/setup.py

@@ -5,8 +5,24 @@
 
 
 def setup_cmd():
-    """Creates setup command"""
+    """
+    Sets up the environment.
 
+    This command allows users to set up the environment for using the CLI.
+
+    Returns
+    -------
+    function
+        The setup command function to be used by the CLI.
+
+    Examples
+    --------
+    Set up the environment with full installation:
+    $ ersilia setup --full
+
+    Set up the environment with base installation:
+    $ ersilia setup --base
+    """
     # Example usage: ersilia setup
     @ersilia_cli.command(
         short_help="Setup ersilia",

ersilia/cli/commands/test.py

@@ -4,11 +4,31 @@
 from ...publish.test import ModelTester
 
 def test_cmd():
+    """
+    Test a model and obtain performance metrics.
 
-# Example usage: ersilia test {MODEL} -d local_dir -l deep --remote
+    This command allows you to test a model using various options to customize the testing process.
+
+    The command performs the following steps:
+    - Sets up the model tester with the specified model and options.
+    - Executes tests to evaluate the model's performance, metadata check, output consistency and more.
+    - Generates and outputs performance metrics.
+
+    Examples
+    --------
+    With default settings:
+    $ ersilia test my_model -d /path/to/model
+
+    With deep testing level and inspect:
+    $ ersilia test my_model -d /path/to/model --level deep --inspect --remote
+    """
     @ersilia_cli.command(
         short_help="Test a model",
-        help="Test a model and obtain performance metrics",
+        help=
+        """
+        Test a local models that are under development as well as on deployment and obtain a detailed report on its expected behavior and performance
+        """
+        ,
     )
     @click.argument("model", type=click.STRING)
     @click.option(
@@ -43,7 +63,7 @@ def test_cmd():
     )
     @click.option(
         "--remove",
-        help="Remove the model after testing", 
+        help="Remove the model directory after testing", 
         is_flag=True, 
         default=False
     )
@@ -66,4 +86,4 @@ def test(
         echo("Setting up model tester...")
         mt.setup()
         echo("Testing model...")
-        mt.run(output_file=None)  
+        mt.run(output_file=None)

ersilia/cli/create_cli.py

@@ -2,8 +2,18 @@
 from .cmd import Command
 from .commands import ersilia_cli
 
-
 def create_ersilia_cli():
+    """
+    Creates and configures the Ersilia CLI.
+
+    This function initializes the Command class, checks if the user is a contributor,
+    and dynamically imports and executes various CLI commands based on the user's role.
+
+    Returns
+    -------
+    ersilia_cli : module
+        The configured Ersilia CLI module.
+    """
     is_contributor = Auth().is_contributor()
 
     cmd = Command()