dandi-cli readme edit #1170

melster1010 · 2022-12-05T17:29:35Z

Edit readme for stylesheet compliance/grammar/clarity/consistency.

codecov · 2022-12-05T17:36:37Z

Codecov Report

Base: 88.27% // Head: 88.90% // Increases project coverage by +0.63% 🎉

Coverage data is based on head (97555c7) compared to base (0439caf).
Patch has no changes to coverable lines.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1170      +/-   ##
==========================================
+ Coverage   88.27%   88.90%   +0.63%     
==========================================
  Files          73       76       +3     
  Lines        8817     9393     +576     
==========================================
+ Hits         7783     8351     +568     
- Misses       1034     1042       +8

Flag	Coverage Δ
unittests	`88.90% <ø> (+0.63%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
dandi/cli/cmd_validate.py	`73.03% <0.00%> (-0.83%)`	⬇️
dandi/download.py	`88.04% <0.00%> (-0.34%)`	⬇️
dandi/cli/tests/test_ls.py	`100.00% <0.00%> (ø)`
dandi/cli/tests/test_command.py	`100.00% <0.00%> (ø)`
dandi/tests/test_download.py	`100.00% <0.00%> (ø)`
dandi/__init__.py	`70.00% <0.00%> (ø)`
dandi/tests/test_move.py	`100.00% <0.00%> (ø)`
dandi/tests/fixtures.py	`98.56% <0.00%> (+0.30%)`	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

README.md

Co-authored-by: John T. Wodder II <jwodder@users.noreply.github.com>

README.md

yarikoptic · 2022-12-06T16:35:33Z

Thank you @melster1010 !! While you are on the run across all the README's and have a good grip over the purpose etc of components -- would you might taking over dandi/handbook#66 to redo or finish up to bring it over the finish line one way or another (might no longer beneeded)?

melster1010 · 2022-12-07T20:14:21Z

Thank you @melster1010 !! While you are on the run across all the README's and have a good grip over the purpose etc of components -- would you might taking over dandi/handbook#66 to redo or finish up to bring it over the finish line one way or another (might no longer be needed)?

You're welcome @yarikoptic! Roni and I plan to discuss the next phase of my work on the DANDI docs, so I can add that to my backlog for Q1 2023 if that works for you.

yarikoptic · 2022-12-07T20:17:22Z

Roni and I plan to discuss the next phase of my work on the DANDI docs, so I can add that to my backlog for Q1 2023 if that works for you.

sure, unless we finalize it before then.

README.md

waxlamp

This looks good as-is, but I've offered a couple of ideas for improvement along with one suggested change.

If the suggested change will cause confusion, let's move on without it. As for the ideas, we can discuss them here and/or accept their implicit suggestions (mainly of striking much of the content) in this PR.

waxlamp · 2022-12-12T17:02:24Z

README.md

-  -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
-                                  Log level name  [default: INFO]
+ -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
+                                  Log level (case insensitive).  May be
+                                  specified as an integer.  [default: INFO]
  --pdb                           Fall into pdb if errors out
  --help                          Show this message and exit.

 Commands:
-  download  Download a file or entire folder from DANDI
-  ls        List .nwb files and dandisets metadata.
-  organize  (Re)organize files according to the metadata.
-  register  Register a new dandiset in the DANDI archive
-  upload    Upload dandiset (files) to DANDI archive.
-  validate  Validate files for NWB (and DANDI) compliance.
+  delete            Delete dandisets and assets from the server.
+  digest            Calculate file digests
+  download          Download a file or entire folder from DANDI.
+  instances         List known Dandi Archive instances that the CLI can...
+  ls                List .nwb files and dandisets metadata.
+  move              Move or rename assets in a local Dandiset and/or on...
+  organize          (Re)organize files according to the metadata.
+  service-scripts   Various utility operations
+  shell-completion  Emit shell script for enabling command completion.
+  upload            Upload Dandiset files to DANDI Archive.
+  validate          Validate files for NWB and DANDI compliance.
+  validate-bids     Validate BIDS paths.
 ```

-Each of the commands has a set of options to alter their behavior.  Please run
-`dandi COMMAND --help` to get more information, e.g.
+Each of the commands has a set of options to alter its behavior.  Run
+`dandi COMMAND --help` to get more information:

 ```
 $> dandi ls --help
-Usage: dandi ls [OPTIONS] [PATHS]...
-
-  List .nwb files metadata
+Usage: dandi ls [OPTIONS] PATH|URL
+
+  List .nwb files and dandisets metadata.
+
+  The arguments may be either resource identifiers or paths to local
+  files/directories.
+
+  Accepted resource identifier patterns:
+   - DANDI:<dandiset id>[/<version>]
+   - https://dandiarchive.org/...
+   - https://identifiers.org/DANDI:<dandiset id>[/<version id>] (<version id> cannot be 'draft')
+   - https://<server>[/api]/[#/]dandiset/<dandiset id>[/<version>][/files[?location=<path>]]
+   - https://*dandiarchive-org.netflify.app/...
+   - https://<server>[/api]/dandisets/<dandiset id>[/versions[/<version>]]
+   - https://<server>[/api]/assets/<asset id>[/download]
+   - https://<server>[/api]/dandisets/<dandiset id>/versions/<version>/assets/<asset id>[/download]
+   - https://<server>[/api]/dandisets/<dandiset id>/versions/<version>/assets/?path=<path>
+   - dandi://<instance name>/<dandiset id>[@<version>][/<path>]
+   - https://<server>/...

 Options:
  -F, --fields TEXT               Comma-separated list of fields to display.
                                  An empty value to trigger a list of
                                  available fields to be printed out
-  -f, --format [auto|pyout|json|json_pp|yaml]
+  -f, --format [auto|pyout|json|json_pp|json_lines|yaml]
                                  Choose the format/frontend for output. If
                                  'auto', 'pyout' will be used in case of
                                  multiple files, and 'yaml' for a single
                                  file.
+  -r, --recursive                 Recurse into content of
+                                  dandisets/directories. Only .nwb files will
+                                  be considered.
+  -J, --jobs INTEGER              Number of parallel download jobs.  [default:
+                                  6]
+  --metadata [api|all|assets]
+  --schema VERSION                Convert metadata to new schema version
  --help                          Show this message and exit.
 ```


It may be out of scope for this PR, but this section seems like it can be simplified to letting the user know that they can run dandi --help and dandi <subcommand> --help to get manpages. Listing sample output means we'll need to keep updating this section every time the CLI changes its interface.

That had crossed my mind too, wasn't sure how often this changed. Added to my Phase 2 docs backlog for 2023.

waxlamp · 2022-12-12T17:02:57Z

README.md

-## Development/contributing
+## Third-party Components

-Please see [DEVELOPMENT.md](./DEVELOPMENT.md) file.
+**dandi/tests/skip.py** -- from https://github.com/ReproNim/reproman, as of v0.2.1-40-gf4f026d
+Copyright (c) 2016-2020  ReproMan Team


Also out of scope for this PR, but I think this section can be struck. I don't think it adds any useful information about DANDI CLI.

Added to my Phase 2 docs backlog for 2023.

waxlamp · 2022-12-12T17:07:15Z

README.md


-### dandi/tests/skip.py
+* To learn how to interact with the DANDI archive and for examples on how to use the DANDI Client in various use cases,
+see [the handbook](https://www.dandiarchive.org/handbook/).


I think it might be useful to highlight sections of the handbook specifically related to the CLI:

Suggested change

see [the handbook](https://www.dandiarchive.org/handbook/).

see [the handbook](https://www.dandiarchive.org/handbook/),

specifically the sections on using the CLI to

[download](https://www.dandiarchive.org/handbook/12_download/) and

[upload](https://www.dandiarchive.org/handbook/13_upload/) `Dandisets`.

I agree that specific guidance would be useful. Added to my Phase 2 docs backlog for 2023.

yarikoptic · 2022-12-12T17:38:30Z

There are 2 approvals, and documentation can always be improved more, so I will just proceed as is for now. Thanks everyone!!!

dandi-cli readme edit

3d3bb9a

melster1010 added the documentation Changes only affect the documentation label Dec 5, 2022

melster1010 requested review from satra and waxlamp December 5, 2022 17:29

melster1010 self-assigned this Dec 5, 2022

jwodder requested changes Dec 5, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

melster1010 mentioned this pull request Dec 5, 2022

Review and edit README files dandi/handbook#74

Closed

7 tasks

fix spelling

79c829c

Co-authored-by: John T. Wodder II <jwodder@users.noreply.github.com>

yarikoptic reviewed Dec 6, 2022

View reviewed changes

README.md Show resolved Hide resolved

Incorporate review feedback

87c37b0

melster1010 requested review from yarikoptic and jwodder December 7, 2022 20:19

jwodder requested changes Dec 8, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

Update dandi and ls --help output

97555c7

melster1010 requested a review from jwodder December 9, 2022 16:37

jwodder approved these changes Dec 12, 2022

View reviewed changes

waxlamp approved these changes Dec 12, 2022

View reviewed changes

yarikoptic merged commit 4cbadb1 into master Dec 12, 2022

yarikoptic deleted the readme-cli branch December 12, 2022 17:38

melster1010 added a commit that referenced this pull request Jan 26, 2023

Fix outstanding readme issues from pr #1170

fd60d6e

melster1010 mentioned this pull request Jan 26, 2023

Further improve README.md: point to specific sections of handbook, remove lengthy dandi ls --help example #1193

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

dandi-cli readme edit #1170

dandi-cli readme edit #1170

melster1010 commented Dec 5, 2022

codecov bot commented Dec 5, 2022 •

edited

Loading

yarikoptic commented Dec 6, 2022

melster1010 commented Dec 7, 2022

yarikoptic commented Dec 7, 2022

waxlamp left a comment

waxlamp Dec 12, 2022

melster1010 Dec 13, 2022

waxlamp Dec 12, 2022

melster1010 Dec 13, 2022

waxlamp Dec 12, 2022

melster1010 Dec 13, 2022

yarikoptic commented Dec 12, 2022

-see [the handbook](https://www.dandiarchive.org/handbook/).
+see [the handbook](https://www.dandiarchive.org/handbook/),
+specifically the sections on using the CLI to
+[download](https://www.dandiarchive.org/handbook/12_download/) and
+[upload](https://www.dandiarchive.org/handbook/13_upload/) `Dandisets`.

dandi-cli readme edit #1170

dandi-cli readme edit #1170

Conversation

melster1010 commented Dec 5, 2022

codecov bot commented Dec 5, 2022 • edited Loading

Codecov Report

yarikoptic commented Dec 6, 2022

melster1010 commented Dec 7, 2022

yarikoptic commented Dec 7, 2022

waxlamp left a comment

Choose a reason for hiding this comment

waxlamp Dec 12, 2022

Choose a reason for hiding this comment

melster1010 Dec 13, 2022

Choose a reason for hiding this comment

waxlamp Dec 12, 2022

Choose a reason for hiding this comment

melster1010 Dec 13, 2022

Choose a reason for hiding this comment

waxlamp Dec 12, 2022

Choose a reason for hiding this comment

melster1010 Dec 13, 2022

Choose a reason for hiding this comment

yarikoptic commented Dec 12, 2022

codecov bot commented Dec 5, 2022 •

edited

Loading