DOC: update docs to agree with latest state of codebase

[jsheunis]

This PR:

• Should address DOC: update docs to reflect recent state of the package #256
• Removes outdated attention blocks
• adds a section Feature support to the quickstart page and linked to from the introduction page
• adds a Tutorial section with detailed steps on pushing and cloning, +screenshots and example outputs

Preview: https://datalad--260.org.readthedocs.build/projects/dataverse/en/260/

[welcome]

Thanks for opening your first pull request! We are happy to have your contributions 🎉 😄

[adswa]

Adding a few screenshots that may be helpful:

To get a ds_pid, one has to "Add data" on dataverse and create a new dataverse dataset:

(And then fill out at least all required fields and metadata elements; and don't upload any data. Afterwards click save)

Afterwards, you have a draft dataset which gives you the DOI to use as a ds_pid:

[jsheunis]

@adswa perfect, thanks!

[adswa]

If you create a sibling in filetree mode, this is what happens:

❱ datalad add-sibling-dataverse https://demo.dataverse.org doi:10.70122/FK2/ZS0YL3 --mode filetree
add_sibling_dataverse.storage(ok): . [dataverse-storage: https://demo.dataverse.org (DOI: doi:10.70122/FK2/ZS0YL3)]
[INFO   ] Configure additional publication dependency on "dataverse-storage" 
add_sibling_dataverse(ok): . [dataverse: datalad-annex::?type=external&externaltype=dataverse&encryption=none&exporttree=yes&url=https%3A//demo.dataverse.org&doi=doi:10.70122/FK2/ZS0YL3 (DOI: doi:10.70122/FK2/ZS0YL3)]
❱ git remote -v
dataverse	datalad-annex::?type=external&externaltype=dataverse&encryption=none&exporttree=yes&url=https%3A//demo.dataverse.org&doi=doi:10.70122/FK2/ZS0YL3 (fetch)
dataverse	datalad-annex::?type=external&externaltype=dataverse&encryption=none&exporttree=yes&url=https%3A//demo.dataverse.org&doi=doi:10.70122/FK2/ZS0YL3 (push)
dataverse-storage
❱ datalad push --to dataverse
copy(ok): .datalad/.gitattributes (dataset)                                     
copy(ok): .datalad/config (dataset)                                             
copy(ok): .gitattributes (dataset)                                              
copy(ok): my-file (dataset)                                                     
publish(ok): . (dataset) [refs/heads/master->dataverse:refs/heads/master [new branch]]
publish(ok): . (dataset) [refs/heads/git-annex->dataverse:refs/heads/git-annex [new branch]] 
                                                                                            action summary:                                                                               
  copy (ok: 4)
  publish (ok: 2)
datalad push --to dataverse  8.58s user 1.95s system 17% cpu 1:01.30 total

And the result on dataverse:

[jsheunis]

I think the screenshots of creating an empty dataset with a DOI, and the file tree mode, would all probably do well on a separate 'Tutorial' page. I'll do that move now, and keep some basic commands on the quickstart page.

Regarding:

If you create a sibling in filetree mode, this is what happens:

What happens without that mode? and is it worth it to document that case?

[adswa]

If you create a dataverse sibling in annex mode, this is what happens:

❱ datalad add-sibling-dataverse https://demo.dataverse.org doi:10.70122/FK2/NQPP6A --mode annex        
add_sibling_dataverse.storage(ok): . [dataverse-storage: https://demo.dataverse.org (DOI: doi:10.70122/FK2/NQPP6A)]
[INFO   ] Configure additional publication dependency on "dataverse-storage" 
add_sibling_dataverse(ok): . [dataverse: datalad-annex::?type=external&externaltype=dataverse&encryption=none&exporttree=no&url=https%3A//demo.dataverse.org&doi=doi:10.70122/FK2/NQPP6A (DOI: doi:10.70122/FK2/NQPP6A)]
❱ datalad push --to dataverse
copy(ok): my-file (file) [to dataverse-storage...]                                           
publish(ok): . (dataset) [refs/heads/master->dataverse:refs/heads/master [new branch]]                       
publish(ok): . (dataset) [refs/heads/git-annex->dataverse:refs/heads/git-annex [new branch]]                 
                                                                                                            action summary:                                                                                               
  copy (ok: 1)
  publish (ok: 2)
datalad push --to dataverse  8.07s user 1.66s system 16% cpu 1:00.28 total

This is how the result looks like:

[adswa]

I think the screenshots of creating an empty dataset with a DOI, and the file tree mode, would all probably do well on a separate 'Tutorial' page. I'll do that move now, and keep some basic commands on the quickstart page.

I agree - I just didn't know whether this will be part of this PR or not, so to spare you reading through the code to figure out how shit works, I just wanted to dump everything I know in here :)

Regarding:

If you create a sibling in filetree mode, this is what happens:

What happens without that mode? and is it worth it to document that case?

See my comment afterwards. filetree does an export of the dataset which should be human-readable and resemble the worktree of what people see in front of them in their terminal. (though as you can see in the screenshot, file mangling and escaping prevents that somewhat).

The annex mode creates a non-human readable dataverse dataset, but it has the git part and the annex part included, so it has version history.

[adswa]

Here's a glimpse into cloning:

annex mode:

❱ datalad clone 'datalad-annex::?type=external&externaltype=dataverse&encryption=none&exporttree=no&url=https%3A//demo.dataverse.org&doi=doi:10.70122/FK2/NQPP6A' my-clone-of-annex-mode
[INFO   ] Remote origin uses a protocol not supported by git-annex; setting annex-ignore                     
[INFO   ] access to 1 dataset sibling dataverse-storage not auto-enabled, enable with:                       
| 		datalad siblings -d "/tmp/tmp/my-clone-of-annex-mode" enable -s dataverse-storage 
install(ok): /tmp/tmp/my-clone-of-annex-mode (dataset)
(dataverse) adina@muninn in /tmp/tmp
❱ cd my-clone-of-annex-mode 
(dataverse) adina@muninn in /tmp/tmp/my-clone-of-annex-mode on git:master
❱ ls
my-file
(dataverse) adina@muninn in /tmp/tmp/my-clone-of-annex-mode on git:master
❱ datalad siblings -d "/tmp/tmp/my-clone-of-annex-mode" enable -s dataverse-storage
.: dataverse-storage(?) [git]
(dataverse) adina@muninn in /tmp/tmp/my-clone-of-annex-mode on git:master
❱ datalad get my-file
get(ok): my-file (file) [from dataverse-storage...] 

filetree mode

❱ datalad clone 'datalad-annex::?type=external&externaltype=dataverse&encryption=none&exporttree=yes&url=https%3A//demo.dataverse.org&doi=doi:10.70122/FK2/ZS0YL3' my-clone-of-filetree-mode
[INFO   ] Remote origin uses a protocol not supported by git-annex; setting annex-ignore                     
[INFO   ] access to 1 dataset sibling dataverse-storage not auto-enabled, enable with:                       
| 		datalad siblings -d "/tmp/my-clone-of-filetree-mode" enable -s dataverse-storage 
install(ok): /tmp/my-clone-of-filetree-mode (dataset)
(dataverse) adina@muninn in /tmp
❱ cd my-clone-of-filetree-mode 
(dataverse) adina@muninn in /tmp/my-clone-of-filetree-mode on git:master
❱ ls
my-file
(dataverse) adina@muninn in /tmp/my-clone-of-filetree-mode on git:master
❱ datalad siblings -d "/tmp/my-clone-of-filetree-mode" enable -s dataverse-storage 
.: dataverse-storage(?) [git]
(dataverse) adina@muninn in /tmp/my-clone-of-filetree-mode on git:master
❱ datalad get my-file
get(ok): my-file (file) [from dataverse-storage...]    

[mih]

Beautiful! I am indebted!

[welcome]

Congrats on merging your first pull request! 😎 The Datalad team is thankful for your contributions