Minor tweaks and additions to the docs #114

adswa · 2020-07-15T16:18:34Z

This aims to document all current functionality, especially that introduced after the merge of #106.

I have only just started to work on the walk-throughs, therefore this is a work in progress. But I'm away from my keyboard for a few hours, and have pushed so that anyone who wants to can already take a look at this or tackle a walk-through.

DOC: add a tutorial toctree

…ganization in main DL docs DOC: refhandle to cmd overview

- OSF - Outline use cases - clear distinction on what dl-osf can do and what not

DOC: tweaks to authentication, mention env vars

- tweaked installation instructions - brief gist into functionality as a quickstart and tutorial primer

…e to play through use cases

adswa · 2020-07-15T20:44:05Z

A first draft is done. I would be grateful if others could give this a read. Feel free to push changes to this branch.
ping @sappelhoff

mih

This is fantastic! I left a few minor comments.

docs/source/intro.rst

mih · 2020-07-16T06:08:13Z

docs/source/intro.rst

+This tool does not work for data that is stored in a storage service other than the OSF_, and within the OSF, only OSF storage, no other third party storage, is supported.
+Please refer to the list of `special remotes`_ as hosted by the `git-annex`_ website for other storage services and how to use them with DataLad.
+Also, be mindful that OSF storage imposes a maximum file size of 5GB.
+Individual files larger than 5GB can not be published with this extension.


FTR: We could (should?) actually tweak the special remote config to reflect that max filesize and limit chunks in the annex to 5GB or less.

docs/source/settingup.rst

mih · 2020-07-16T06:14:41Z

docs/source/settingup.rst

+.. code-block:: bash
+
+   # inside of a DataLad dataset
+   $ datalad create-sibling-osf --title best-study-ever -s osf


osf is the default name, so it could be stripped

thx, but I feel as if it would be helpful to be verbose here. I fear that else the --to osf is not as easily identified as a configurable, arbitrary name but as a generic way to refer to "the OSF"

fine with me

thx, but I feel as if it would be helpful to be verbose here. I fear that else the --to osf is not as easily identified as a configurable, arbitrary name but as a generic way to refer to "the OSF"

I agree with this 👍

is -s the shortform? or is there a --long_form_of_s? If there is a long form, I think it'd be preferable to use here, because short forms are often abbreviations that can interrupt the reading flow.

Its -s/--name. I won't defend this decision at all costs, but the cheatsheet also mentions (only) the short form.

And in this particular command, its also not easy to relate --title and --name to project versus sibling name. -s is more likely the sibling wherease --name is more ambiguous.

true, fair points 👍

docs/source/tutorial/authentication.rst

docs/source/tutorial/osf-sibling.rst

docs/source/acknowledgements.rst

sappelhoff · 2020-07-16T06:54:51Z

docs/source/intro.rst

+It comes with several features that enable the following main use cases:
+
+#. Export existing datasets to the OSF
+#. Clone published datasets from the OSF


Is this possible right now?

yes, but not on windows #112

you could give "usecase 1" a test run

docs/source/intro.rst

docs/source/settingup.rst

sappelhoff · 2020-07-16T07:02:23Z

docs/source/settingup.rst

+.. code-block:: bash
+
+   # inside of a DataLad dataset
+   $ datalad create-sibling-osf --title best-study-ever -s osf


thx, but I feel as if it would be helpful to be verbose here. I fear that else the --to osf is not as easily identified as a configurable, arbitrary name but as a generic way to refer to "the OSF"

I agree with this 👍

is -s the shortform? or is there a --long_form_of_s? If there is a long form, I think it'd be preferable to use here, because short forms are often abbreviations that can interrupt the reading flow.

adswa · 2020-07-16T07:09:21Z

The preview is here: https://datalad--114.org.readthedocs.build/projects/osf/en/114/

sappelhoff

I did a pass through the docs and left my comments :-)

One more comment: Great job!

docs/source/tutorial/exportdatacode.rst

sappelhoff · 2020-07-16T07:14:17Z

docs/source/tutorial/exportdatacode.rst

+
+.. image:: ../_static/datastore_sibling.png
+
+This way you can let OSF handle your data and GitHub your code.


Having read this tutorial, I am not really sure about the benefit of having the dataset published via GitHub as well (i.e., data on OSF, ... can be datalad installed through OSF or GitHub).

thx, have pushed an improvement. Personally I also don't see much need for the usecase anymore, but it was one of the major usecases in 0.1 and remains generally possible, so why not (keep it) documented :)

docs/source/tutorial/exporthumandata.rst

sappelhoff · 2020-07-16T07:24:37Z

you may want to fix this typo as well

datalad-osf/datalad_osf/create_sibling_osf.py

Lines 147 to 148 in 7b09c60

    
                       the associated project page. By default a description will 
        
                       generated based on the mode the sibling is put into.""",

- will generated
+ will be generated

Co-authored-by: Stefan Appelhoff <[email protected]>

…c-overhaul

adswa · 2020-07-16T07:42:29Z

thanks all for feedback and suggestions, its all done. I'll merge this in for now, a fix for #116 will need to remove the 5GB file size limitation. I may try to tackle chunking later today. :)

adswa added 16 commits July 15, 2020 12:12

DOC: Fix extension name and copyright

03e0650

DOC: add project logo

3cf7f9a

DOC: restructure demonstrations to be a tutorial part

6ea615e

DOC: add a tutorial toctree

DOC: seperate toctrees and files for Python API and CMD, mimicking or…

3e165f8

…ganization in main DL docs DOC: refhandle to cmd overview

DOC: More elaborate introduction

cf83782

- OSF - Outline use cases - clear distinction on what dl-osf can do and what not

DOC: Tweak the index page

787812a

DOC: add acknowledgements (taken + modified from datalad)

d1b520a

DOC: add contributing section

8d4a7da

DOC: start the tutorial with authentication

2d084f0

DOC: tweaks to authentication, mention env vars

DOC: general section on osf-sibling command

c5307a6

DOC: minor typo in docstring

87698a6

DOC: more common links

71aab5b

DOC: overhaul getting started section

c674917

- tweaked installation instructions - brief gist into functionality as a quickstart and tutorial primer

DOC: adjust walk-throughs

08bc3e2

DOC: Create a common tutorial dataset for everyone to recreate and us…

d5b9f83

…e to play through use cases

DOC: minor improvements to the authentication section

e53abbe

adswa force-pushed the doc-overhaul branch from 584ff60 to e53abbe Compare July 15, 2020 20:40

adswa changed the title ~~[WIP] Minor tweaks and additions to the docs~~ Minor tweaks and additions to the docs Jul 15, 2020

adswa mentioned this pull request Jul 16, 2020

Enable PR builds on Readthedocs #115

Closed

DOC: gentle tweaks and improvements

485ddb3

mih approved these changes Jul 16, 2020

View reviewed changes

mih mentioned this pull request Jul 16, 2020

Release 0.2 #117

Closed

mih reviewed Jul 16, 2020

View reviewed changes

docs/source/acknowledgements.rst Show resolved Hide resolved

adswa added 3 commits July 16, 2020 08:40

DOC: use current grant numbers in acknowledgements

a87c57e

DOC: warn windows users and strip development installation

365b666

DOC: minor fixes from mih's comments

932221f

sappelhoff reviewed Jul 16, 2020

View reviewed changes

trigger build again

83888d3

sappelhoff reviewed Jul 16, 2020

View reviewed changes

adswa and others added 6 commits July 16, 2020 09:30

DOC: typo sweep with aspell

a1db290

Typo

d3b5784

Co-authored-by: Stefan Appelhoff <[email protected]>

Update docs/source/tutorial/exportdatacode.rst

f8b1bbd

Co-authored-by: Stefan Appelhoff <[email protected]>

Update docs/source/tutorial/exporthumandata.rst

3459aca

Co-authored-by: Stefan Appelhoff <[email protected]>

DOC: final fixes

4e9f948

Merge branch 'doc-overhaul' of github.com:datalad/datalad-osf into do…

8419777

…c-overhaul

adswa merged commit 25988f8 into master Jul 16, 2020

adswa deleted the doc-overhaul branch July 16, 2020 07:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Minor tweaks and additions to the docs #114

Minor tweaks and additions to the docs #114

adswa commented Jul 15, 2020

adswa commented Jul 15, 2020

mih left a comment

mih Jul 16, 2020

mih Jul 16, 2020

adswa Jul 16, 2020

mih Jul 16, 2020

adswa Jul 16, 2020

mih Jul 16, 2020

sappelhoff Jul 16, 2020

adswa Jul 16, 2020

sappelhoff Jul 16, 2020

sappelhoff Jul 16, 2020

mih Jul 16, 2020 •

edited

Loading

adswa Jul 16, 2020 •

edited

Loading

sappelhoff Jul 16, 2020

adswa commented Jul 16, 2020

sappelhoff left a comment

sappelhoff Jul 16, 2020

adswa Jul 16, 2020

sappelhoff commented Jul 16, 2020

adswa commented Jul 16, 2020


		.. image:: ../_static/datastore_sibling.png

		This way you can let OSF handle your data and GitHub your code.

Minor tweaks and additions to the docs #114

Minor tweaks and additions to the docs #114

Conversation

adswa commented Jul 15, 2020

adswa commented Jul 15, 2020

mih left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mih Jul 16, 2020 • edited Loading

Choose a reason for hiding this comment

adswa Jul 16, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adswa commented Jul 16, 2020

sappelhoff left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sappelhoff commented Jul 16, 2020

adswa commented Jul 16, 2020

mih Jul 16, 2020 •

edited

Loading

adswa Jul 16, 2020 •

edited

Loading