Add links to the query api page in view and find --help

doc/requirements.txt

@@ -1,3 +1,4 @@
+argparse-formatter>=1.4
 sphinx>=4.0.0
 sphinx_rtd_theme>=1.0.0
 sphinxcontrib-programoutput

requirements.txt

@@ -1,3 +1,4 @@
+argparse-formatter>=1.4
 filelock>=3.0
 packaging>=15.0
 tqdm>=4.10.0

signac/__main__.py

@@ -21,6 +21,7 @@
 from pprint import pformat, pprint
 from rlcompleter import Completer
 
+from argparse_formatter import FlexiFormatter
 from tqdm import tqdm
 
 try:
@@ -1266,7 +1267,7 @@ def main():
         "-c",
         "--create",
         action="store_true",
-        help="Create the job's workspace directory if necessary.",
+        help="Create the job directory if necessary.",
     )
     parser_job.set_defaults(func=main_job)
 
@@ -1468,9 +1469,17 @@ def main():
 
     parser_find = subparsers.add_parser(
         "find",
-        description="""All filter arguments may be provided either directly in JSON
-                       encoding or in a simplified form, e.g., -- $ signac find a 42 --
-                       is equivalent to -- $ signac find '{"a": 42}'.""",
+        formatter_class=FlexiFormatter,
+        description="""
+        All filter arguments may be provided either directly in JSON
+        encoding or in a simplified form using the query API. For
+        example, the following two bash commands are equivalent:
+
+        $ signac find key 42
+        $ signac find '{"a": 42}'
+
+        For the full syntax, see:
+        https://docs.signac.io/en/latest/query.html#simplified-filter""",  # noqa:E501
     )
     parser_find.add_argument(
         "filter",
@@ -1527,17 +1536,23 @@ def main():
 
     parser_view = subparsers.add_parser(
         "view",
-        description="""Generate a human readable set of paths representing
-                           state points in the workspace, e.g.
-                           view/param_name_1/param_value_1/param_name_2/param_value_2/job.
-                           The leaf nodes of this directory structure are
-                           symlinks (named "job") into the workspace directory
-                           for that parameter combination. Note that all
-                           positional arguments must be provided before any
-                           keyword arguments. In particular, the prefix and
-                           path must be specified before arguments such as the
-                           filters, e.g.  signac view $PREFIX $VIEW_PATH -f
-                           FILTERS -d DOC_FILTERS.""",  # noqa:E501
+        formatter_class=FlexiFormatter,
+        description="""
+        Generate a human readable set of paths
+        representing state points in the workspace,
+        e.g. view/param_name_1/param_value_1/param_name_2/param_value_2/job.
+
+        The leaf nodes of this directory structure are symlinks (named
+        "job") into the corresponding job directory.
+
+        The jobs can be filtered using the query API used by the find
+        command. See
+        https://docs.signac.io/en/latest/query.html#simplified-filter
+
+        All positional arguments must be provided before any keyword
+        arguments. In particular, the prefix and path must be
+        specified before arguments such as the filters, e.g. signac
+        view $PREFIX $VIEW_PATH -f FILTERS -d DOC_FILTERS.""",  # noqa:E501
     )
     parser_view.add_argument(
         "prefix",
@@ -1674,14 +1689,17 @@ def main():
 
     parser_sync = subparsers.add_parser(
         "sync",
-        description="""Use this command to synchronize this project with another project;
-similar to the synchronization of two directories with `rsync`.
-Data is always copied from the source to the destination.
-For example: `signac sync /path/to/other/project -u --all-keys`
-means "Synchronize all jobs within this project with those in the other project; overwrite
-files if the source files is newer and overwrite all conflicting keys in the project and
-job documents."
-""",
+        formatter_class=FlexiFormatter,
+        description="""
+        Use this command to synchronize this project with another
+        project; similar to the synchronization of two directories
+        with `rsync`. Data is always copied from the source to the
+        destination.
+
+        For example: `signac sync /path/to/other/project -u --all-keys` means
+        "Synchronize all jobs within this project with those in the other
+        project; overwrite files if the source files is newer and overwrite
+        all conflicting keys in the project and job documents.""",
     )
     parser_sync.add_argument(
         "source",