Merge pull request #1437 from asmacdo/clarify-download-docs

clarify resource identifier docs

dandi/cli/cmd_download.py

@@ -11,16 +11,44 @@
 from ..download import DownloadExisting, DownloadFormat, PathType
 from ..utils import get_instance, joinurl
 
+_examples = """
+EXAMPLES:\n
+# Download only the dandiset.yaml\n
+dandi download --download dandiset.yaml DANDI:000027\n
+
+# Download only dandiset.yaml if there is a newer version\n
+dandi download https://identifiers.org/DANDI:000027 --existing refresh
+
+# Download only the assets\n
+dandi download --download assets DANDI:000027
+
+# Download all from a specific version\n
+dandi download DANDI:000027/0.210831.2033
+
+# Download a specific directory\n
+dandi download dandi://DANDI/000027@0.210831.2033/sub-RAT123/
+
+# Download a specific file\n
+dandi download dandi://DANDI/000027@0.210831.2033/sub-RAT123/sub-RAT123.nwb
+"""
+
 
 # The use of f-strings apparently makes this not a proper docstring, and so
 # click doesn't use it unless we explicitly assign it to `help`:
 @click.command(
     help=f"""\
 Download files or entire folders from DANDI.
 
+\b
+{_dandi_url_parser.resource_identifier_primer}
+
 \b
 {_dandi_url_parser.known_patterns}
-    """
+
+\b
+{_examples}
+
+"""
 )
 @click.option(
     "-o",

dandi/cli/cmd_ls.py

@@ -26,6 +26,8 @@
 The arguments may be either resource identifiers or paths to local
 files/directories.
 
+\b
+{_dandi_url_parser.resource_identifier_primer}
 \b
 {_dandi_url_parser.known_patterns}
 """

dandi/dandiarchive.py

@@ -675,6 +675,16 @@ class _dandi_url_parser:
             "https://<server>/...",
         ),
     ]
+    resource_identifier_primer = """RESOURCE ID/URLS:\n
+    dandi commands accept URLs and URL-like identifiers called <resource
+    ids> in the following formats for identifying Dandisets, assets, and
+    asset collections.
+
+    Text in [brackets] is optional.  A server field is a base API or GUI URL
+    for a DANDI Archive instance.  If an optional ``version`` field is
+    omitted from a URL, the given Dandiset's most recent published version
+    will be used if it has one, and its draft version will be used otherwise.
+    """
     known_patterns = "Accepted resource identifier patterns:" + "\n - ".join(
         [""] + [display for _, _, display in known_urls]
     )