-
Notifications
You must be signed in to change notification settings - Fork 25
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
ENH: adding sphinx documentation for the dandi-cli #712
Merged
Merged
Changes from 1 commit
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
56333d7
rename doc to docs for consistency with e.g. datalad
yarikoptic c82d191
DOC: skeleton made by sphinx-quickstart for sphinx docs
yarikoptic 481b620
initial bits and pieces
yarikoptic 02bf07f
Build with tox
jwodder 5c1348c
Show more details for dandiapi and dandiarchive
jwodder d8ae55e
More docs pages
jwodder b6224fb
Make --jobs arg consistent
jwodder 385fbe8
Add "Build Docs" workflow
jwodder 6ef7fa9
Typo
jwodder 7b6a862
Fix Sphinx warnings and convert new ones into errors
jwodder File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
:program:`dandi delete` | ||
======================= | ||
|
||
:: | ||
|
||
dandi [<global options>] delete [<options>] [<paths> ...] | ||
|
||
Delete dandisets and assets from the server. | ||
|
||
PATH could be a local path or a URL to an asset, directory, or an entire | ||
dandiset. | ||
|
||
Options | ||
------- | ||
|
||
.. option:: --skip-missing | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
:program:`dandi digest` | ||
======================= | ||
|
||
:: | ||
|
||
dandi [<global options>] digest [<options>] [<path> ...] | ||
|
||
Calculate file digests | ||
|
||
Options | ||
------- | ||
|
||
.. option:: -d, --digest [dandi-etag|md5|sha1|sha256|sha512] | ||
|
||
Digest algorithm to use [default: dandi-etag] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
:program:`dandi download` | ||
========================= | ||
|
||
:: | ||
|
||
dandi [<global options>] download [<options>] [<url> ...] | ||
|
||
Options | ||
------- | ||
|
||
.. option:: -o, --output-dir <dir> | ||
|
||
Directory where to download to (directory must exist). Files will be | ||
downloaded with paths relative to that directory. | ||
|
||
.. option:: -e, --existing [error|skip|overwrite|overwrite-different|refresh] | ||
|
||
What to do if a file found existing locally. 'refresh': verify | ||
that according to the size and mtime, it is the same file, if not - | ||
download and overwrite. | ||
|
||
.. option:: -f, --format [pyout|debug] | ||
|
||
Choose the format/frontend for output. | ||
|
||
.. option:: -J, --jobs INT | ||
|
||
Number of parallel download jobs. | ||
|
||
.. option:: --download [dandiset.yaml,assets,all] | ||
|
||
Comma-separated list of elements to download | ||
|
||
.. option:: --sync | ||
|
||
Delete local assets that do not exist on the server |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
********************** | ||
Command-Line Interface | ||
********************** | ||
|
||
.. toctree:: | ||
:glob: | ||
|
||
* |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
:program:`dandi ls` | ||
=================== | ||
|
||
:: | ||
|
||
dandi [<global options>] ls [<options>] [<path|url> ...] | ||
|
||
List .nwb files and dandisets metadata. | ||
|
||
Patterns for known setups: | ||
|
||
- ``DANDI:<dandiset id>`` | ||
- ``https://dandiarchive.org/...`` | ||
- ``https://identifiers.org/DANDI:<dandiset id>`` | ||
- ``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]/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 | ||
------- | ||
|
||
.. option:: -F, --fields <fields> | ||
|
||
Comma-separated list of fields to display. An empty value to trigger a | ||
list of available fields to be printed out | ||
|
||
.. option:: -f, --format [auto|pyout|json|json_pp|json_lines|yaml] | ||
|
||
Choose the format/frontend for output. If 'auto' (default), 'pyout' will be | ||
used in case of multiple files, and 'yaml' for a single file. | ||
|
||
.. option:: -r, --recursive | ||
|
||
Recurse into content of dandisets/directories. Only .nwb files will be | ||
considered. | ||
|
||
.. option:: -J, --jobs <int> | ||
|
||
Number of parallel download jobs. | ||
|
||
.. option:: --metadata [api|all|assets] | ||
|
||
.. option:: --schema <version> | ||
|
||
Convert metadata to new schema version |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
:program:`dandi organize` | ||
========================= | ||
|
||
:: | ||
|
||
dandi [<global options>] organize [<options>] [<path> ...] | ||
|
||
(Re)organize files according to the metadata. | ||
|
||
The purpose of this command is to take advantage of metadata contained in the | ||
.nwb files to provide datasets with consistently named files, so their naming | ||
reflects data they contain. | ||
|
||
.nwb files are organized into a hierarchy of subfolders one per each "subject", | ||
e.g. sub-0001 if .nwb file had contained a Subject group with subject_id=0001. | ||
Each file in a subject-specific subfolder follows the convention:: | ||
|
||
sub-<subject_id>[_key-<value>][_mod1+mod2+...].nwb | ||
|
||
where following keys are considered if present in the data:: | ||
|
||
ses -- session_id | ||
tis -- tissue_sample_id | ||
slice -- slice_id | ||
cell -- cell_id | ||
|
||
and ``modX`` are "modalities" as identified based on detected neural data types | ||
(such as "ecephys", "icephys") per extensions found in nwb-schema definitions: | ||
https://github.com/NeurodataWithoutBorders/nwb-schema/tree/dev/core | ||
|
||
In addition an "obj" key with a value corresponding to crc32 checksum of | ||
"object_id" is added if aforementioned keys and the list of modalities are | ||
not sufficient to disambiguate different files. | ||
|
||
You can visit https://dandiarchive.org for a growing collection of | ||
(re)organized dandisets. | ||
|
||
Options | ||
------- | ||
|
||
.. options:: -d, --dandiset-path <dir> | ||
|
||
A top directory (local) of the dandiset to organize files under. If not | ||
specified, dandiset current directory is under is assumed. For 'simulate' | ||
mode target dandiset/directory must not exist. | ||
|
||
.. option:: --invalid [fail|warn] | ||
|
||
What to do if files without sufficient metadata are encountered. | ||
|
||
.. option:: -f, --files-mode [dry|simulate|copy|move|hardlink|symlink|auto] | ||
|
||
If 'dry' - no action is performed, suggested renames are printed. If | ||
'simulate' - hierarchy of empty files at --local-top-path is created. Note | ||
that previous layout should be removed prior this operation. If 'auto' | ||
(default) - whichever of symlink, hardlink, copy is allowed by system. The | ||
other modes (copy, move, symlink, hardlink) define how data files should be | ||
made available. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
:program:`dandi shell-completion` | ||
================================= | ||
|
||
:: | ||
|
||
dandi [<global options>] shell-completion [<options>] | ||
|
||
Emit shell script for enabling command completion. | ||
|
||
The output of this command should be "sourced" by bash or zsh to enable command | ||
completion. | ||
|
||
Example:: | ||
|
||
$ source <(dandi shell-completion) | ||
$ dandi --<PRESS TAB to display available option> | ||
|
||
Options | ||
------- | ||
|
||
.. option:: -s, --shell [bash|zsh|fish|auto] | ||
|
||
The shell for which to generate completion code; `auto` (default) attempts | ||
autodetection |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
:program:`dandi upload` | ||
======================= | ||
|
||
:: | ||
|
||
dandi [<global options>] upload [<options>] [<path> ...] | ||
|
||
Upload dandiset (files) to DANDI archive. | ||
|
||
Target dandiset to upload to must already be registered in the archive and | ||
locally :file:`dandiset.yaml` should exist in :option:`--dandiset-path`. | ||
|
||
Local dandiset should pass validation. For that it should be first organized | ||
using ``dandi organize`` command. | ||
|
||
By default all files in the dandiset (not following directories starting with a | ||
period) will be considered for the upload. You can point to specific files you | ||
would like to validate and have uploaded. | ||
|
||
Options | ||
------- | ||
|
||
.. option:: -e, --existing [error|skip|force|overwrite|refresh] | ||
|
||
What to do if a file found existing on the server. 'skip' would skip the | ||
file, 'force' - force reupload, 'overwrite' - force upload if either size | ||
or modification time differs; 'refresh' (default) - upload only if local | ||
modification time is ahead of the remote. | ||
|
||
.. option:: -J, --jobs N[:M] | ||
|
||
Number of files to upload in parallel and, optionally, number of upload | ||
threads per file | ||
|
||
.. option:: --sync | ||
|
||
Delete assets on the server that do not exist locally | ||
|
||
.. option:: --validation [require|skip|ignore] | ||
|
||
Data must pass validation before the upload. Use of this option is highly | ||
discouraged. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
:program:`dandi validate` | ||
========================= | ||
|
||
:: | ||
|
||
dandi [<global options>] validate [<path> ...] | ||
|
||
Validate files for NWB (and DANDI) compliance. | ||
|
||
Exits with non-0 exit code if any file is not compliant. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
``dandi.consts`` | ||
================ | ||
|
||
.. automodule:: dandi.consts |
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
``dandi.support.digests`` | ||
========================= | ||
|
||
.. automodule:: dandi.support.digests |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
``dandi.utils`` | ||
=============== | ||
|
||
.. automodule:: dandi.utils |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
oh -- you just manually produced them? great for now but we should look into making them generated automagically... may be smth like https://github.com/click-contrib/sphinx-click could be used ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't really like the way the sphinx-click output looks.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
May be there is a way to improve that? I just fear that manually produced docs would quickly become our of sync with actual CLI