Update cli docs

docs/guide/cli/cli_basics.rst

@@ -13,30 +13,30 @@ To get a list of the subcommands and their descriptions, call ``openfe`` (or
 .. code:: none
 
     Usage: openfe [OPTIONS] COMMAND [ARGS]...
-    
+
       This is the command line tool to provide easy access to functionality from
       the OpenFE Python library.
-    
+
     Options:
       --version   Show the version and exit.
       --log PATH  logging configuration file
       -h, --help  Show this message and exit.
-    
+
     Network Planning Commands:
-      view-ligand-network  Visualize a ligand network
-      plan-rbfe-network    Plan a relative binding free energy network, saved as
-                           JSON files for the quickrun command.
       plan-rhfe-network    Plan a relative hydration free energy network, saved as
-                           JSON files for the quickrun command.
-
+                          JSON files for the quickrun command.
+      plan-rbfe-network    Plan a relative binding free energy network, saved as
+                          JSON files for the quickrun command.
+      view-ligand-network  Visualize a ligand network
+
     Quickrun Executor Commands:
       gather    Gather result jsons for network of RFE results into a TSV file
       quickrun  Run a given transformation, saved as a JSON file
-    
+
     Miscellaneous Commands:
-      fetch  Fetch tutorial or other resource.
+      fetch             Fetch tutorial or other resource.
       charge-molecules  Generate partial charges for a set of molecules.
-      test   Run the OpenFE test suite
+      test              Run the OpenFE test suite
 
 The ``--log`` option takes a logging configuration file and sets that
 logging behavior. If you use it, it must come before the subcommand name.
@@ -47,26 +47,28 @@ the subcommand name, e.g., ``openfe quickrun --help``, which returns
 .. code:: none
 
     Usage: openfe quickrun [OPTIONS] TRANSFORMATION
-    
+
       Run the transformation (edge) in the given JSON file.
-    
+
       Simulation JSON files can be created with the :ref:`cli_plan-rbfe-network`
-      or from Python a :class:`.Transformation` can be saved using its ``to_json``
+      or from Python a :class:`.Transformation` can be saved using its to_json
       method::
-    
+
           transformation.to_json("filename.json")
-    
+
       That will save a JSON file suitable to be input for this command.
-    
+
       Running this command will execute the simulation defined in the JSON file,
       creating a directory for each individual task (``Unit``) in the workflow.
       For example, when running the OpenMM HREX Protocol a directory will be
       created for each repeat of the sampling process (by default 3).
-    
+
     Options:
-      -d, --work-dir DIRECTORY  directory to store files in (defaults to current
-                                directory)
-      -o FILE                   output file (JSON format) for the final results
+      -d, --work-dir DIRECTORY  Directory in which to store files in (defaults to
+                                current directory). If the directory does not
+                                exist, it will be created at runtime.
+      -o PATH                   Filepath at which to create and write the JSON-
+                                formatted results.
       -h, --help                Show this message and exit.
 
 For more details on various commands, see the :ref:`cli-reference`.

docs/guide/cli/cli_yaml.rst

@@ -89,16 +89,16 @@ Customising the partial charge generation
 
 There are a range of partial charge generation schemes available, including
 
-    - ``am1bcc``
-    - ``am1bccelf10`` (only possible if ``off_toolkit_backend`` in settings is set to ``openeye``)
-    - ``nagl`` (must have ``openff-nagl`` installed)
-    - ``espaloma`` (must have ``espaloma_charge`` installed)
+* ``am1bcc``
+* ``am1bccelf10`` (only possible if ``off_toolkit_backend`` in settings is set to ``openeye``)
+* ``nagl`` (must have ``openff-nagl`` installed)
+* ``espaloma`` (must have ``espaloma_charge`` installed)
 
 The following settings can also be set
 
-    - ``off_toolkit_backend`` The backend to use for partial charge generation. Choose from  ``ambertools`` (default), ``openeye`` or ``rdkit``.
-    - ``number_of_conformers`` The number of conformers to use for partial charge generation. If unset (default), the input conformer will be used.
-    - ``nagl_model``: The NAGL model to use. If unset (default), the latest available production charge model will be used.
+* ``off_toolkit_backend`` The backend to use for partial charge generation. Choose from  ``ambertools`` (default), ``openeye`` or ``rdkit``.
+* ``number_of_conformers`` The number of conformers to use for partial charge generation. If unset (default), the input conformer will be used.
+* ``nagl_model``: The NAGL model to use. If unset (default), the latest available production charge model will be used.
 
 For example, to generate the partial charges using the ``am1bccelf10`` method from ``openeye`` the following should be added to the YAML settings file ::
 

docs/guide/index.rst

@@ -2,6 +2,7 @@ User Guide
 ==========
 
 .. toctree::
+    :maxdepth: 2
 
     introduction
     setup/index

docs/reference/cli/index.rst

@@ -6,8 +6,8 @@ CLI Reference
 .. toctree::
     :maxdepth: 1
 
+    charge_molecules
     plan_rhfe_network
     plan_rbfe_network
     quickrun
     gather
-    charge_molecules

openfecli/commands/generate_partial_charges.py

@@ -4,6 +4,27 @@
 from openfecli import OFECommandPlugin
 from openfecli.parameters import MOL_DIR, YAML_OPTIONS, OUTPUT_FILE_AND_EXT, NCORES, OVERWRITE
 
+YAML_HELP = """
+Path to a YAML file specifying the method to use to charge the molecules
+(any atom mapper or network generation options will be ignored).
+
+Supported partial charge method choices are:
+    - ``am1bcc``
+    - ``am1bccelf10`` (only possible if ``off_toolkit_backend`` is ``openeye``)
+    - ``nagl`` (must have openff-nagl installed)
+    - ``espaloma`` (must have espaloma_charge installed)
+
+``settings`` allows for passing in any keyword arguments of the method's corresponding Python API.
+
+For example:
+::
+
+  partial_charge:
+    method: am1bcc
+    settings:
+      off_toolkit_backend: ambertools
+
+"""
 
 @click.command(
     "charge-molecules",
@@ -14,7 +35,7 @@
 )
 @YAML_OPTIONS.parameter(
     multiple=False, required=False, default=None,
-    help=YAML_OPTIONS.kwargs["help"],
+    help=YAML_HELP,
 )
 @OUTPUT_FILE_AND_EXT.parameter(
     help="The name of the SDF file the charged ligands should be written to.",

openfecli/commands/plan_rhfe_network.py

@@ -132,13 +132,13 @@ def plan_rhfe_network(molecules: List[str], yaml_settings: str, output_dir: str,
     The tool will parse the input and run the rbfe network planner, which
     executes following steps:
 
-        1. generate an atom mapping for all possible ligand pairs. (default:
-           Lomap)
+    1. generate an atom mapping for all possible ligand pairs. (default:
+        Lomap)
 
-        2. score all atom mappings. (default: Lomap default score)
+    2. score all atom mappings. (default: Lomap default score)
 
-        3. build network form all atom mapping scores (default: minimal
-           spanning graph)
+    3. build network form all atom mapping scores (default: minimal
+        spanning graph)
 
     The generated Network will be stored in a folder containing for each
     transformation a JSON file, that can be run with quickrun (or other

openfecli/commands/quickrun.py

@@ -27,8 +27,8 @@ def _format_exception(exception) -> str:
     type=click.Path(dir_okay=True, file_okay=False, writable=True,
                     path_type=pathlib.Path),
     help=(
-        "Directory in which to store files in (defaults to current directory).\
-        If the directory does not exist, it will be created at runtime."
+        "Directory in which to store files in (defaults to current directory). "
+        "If the directory does not exist, it will be created at runtime."
     ),
 )
 @click.option(

openfecli/parameters/misc.py

@@ -4,10 +4,10 @@
 N_PROTOCOL_REPEATS = Option(
     "--n-protocol-repeats",
     type=click.INT,
-    help="Number of independent repeats(s) to be run per execution of a transformation using the `openfe quickrun` command.\n\n"
-    "For example:\n\n  `--n-protocol-repeats=3` means `openfe quickrun` will execute 3 repeats in serial.\n\n"
-    "  `--n-protocol-repeats=1` means `openfe quickrun` will execute only 1 repeat per call, "
-    "which allows for individual repeats to be submitted in parallel by calling `openfe quickrun` on the same input JSON file multiple times.",
+    help="Number of independent repeats(s) to be run per execution of a transformation using the ``openfe quickrun`` command.\n\n"
+    "For example:\n\n  ``--n-protocol-repeats=3`` means ``openfe quickrun`` will execute 3 repeats in serial.\n\n"
+    "  ``--n-protocol-repeats=1`` means ``openfe quickrun`` will execute only 1 repeat per call, "
+    "which allows for individual repeats to be submitted in parallel by calling ``openfe quickrun`` on the same input JSON file multiple times.",
 )
 
 NCORES = Option(

openfecli/parameters/plan_network_options.py

@@ -213,25 +213,45 @@ def load_yaml_planner_options(path: Optional[str], context) -> PlanNetworkOption
         solvent,
         partial_charge_settings,
     )
-
+# TODO: do we want this in the docs anywhere?
+DEFAULT_YAML="""
+    mapper: LomapAtomMapper
+        settings:
+            time: 20
+            threed: True
+            max3d: 1.0
+            element_change: true
+            seed: ''
+            shift: false
+
+    network:
+        method: generate_minimal_spanning_network
+
+    partial_charge:
+        method: am1bcc
+        settings:
+            off_toolkit_backend: ambertools
+            number_of_conformers: None
+            nagl_model: None
+"""
 
 _yaml_help = """
 Path to a YAML file specifying the atom mapper (``mapper``), network planning algorithm (``network``),
 and/or partial charge method (``partial_charge``) to use.
 
 \b
 Supported atom mapper choices are:
-    - ``LomapAtomMapper``
+    - ``LomapAtomMapper`` (default)
     - ``KartografAtomMapper``
 \b
 Supported network planning algorithms include (but are not limited to):
-    - ``generate_minimal_spanning_tree``
+    - ``generate_minimal_spanning_network`` (default)
     - ``generate_minimal_redundant_network``
     - ``generate_radial_network``
     - ``generate_lomap_network``
 \b
 Supported partial charge method choices are:
-    - ``am1bcc``
+    - ``am1bcc`` (default)
     - ``am1bccelf10`` (only possible if ``off_toolkit_backend`` is ``openeye``)
     - ``nagl`` (must have openff-nagl installed)
     - ``espaloma`` (must have espaloma_charge installed)