Merge pull request #301 from datalad/doc-300

Add description template snippet for copy-pasting

docs/source/conf.py

@@ -62,6 +62,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
+    'sphinx_copybutton',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',

docs/source/settingup.rst

@@ -151,6 +151,42 @@ Once the dataset is available on Dataverse, it can also be cloned using the
       'datalad-annex::?type=external&externaltype=dataverse&encryption=none&exporttree=no&url=https%3A//demo.dataverse.org&doi=doi:10.70122/MYT/ESTDOI'
 
 
+Help others getting started
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Its not always obvious to outsiders whether a Dataverse Dataset is a DataLad Dataset as well.
+To help others get started with your shared datasets, we recommend to add a short DataLad-specific description to your dataset's "Description" metadata.
+For convenience, a template to copy-and-paste can be found below.
+
+.. code-block:: text
+
+   This dataset is a <b>DataLad dataset</b> (https://www.datalad.org), published with
+   the datalad-dataverse software (https://docs.datalad.org/projects/dataverse).
+   If you <code>"datalad clone"</code> it, it provides fine-grained data access down to the
+   level of individual files, and allows for tracking future updates. For this,
+   DataLad and datalad-dataverse are required. You can find installation instructions
+   at https://docs.datalad.org/projects/dataverse/settingup.html#installation.
+   Afterwards, you can clone it with the following command-line call (replace
+   the two placeholders <code>DATAVERSE-INSTANCE-URL</code> and <code>DATASET-DOI</code>): <br><br>
+
+       <code>datalad clone 'datalad-annex::?type=external&externaltype=dataverse&encryption=none&exporttree=no&url=DATAVERSE-INSTANCE-URL&doi=DATASET-DOI' my-dataset-clone</code> <br><br>
+
+   Once a dataset is cloned, it is a light-weight directory on your local
+   machine.
+   At this point, it contains only small metadata and information on the
+   identity of the files in the dataset, but not actual *content* of the
+   (sometimes large) data files.
+   After cloning a dataset, you can retrieve file contents from available locations
+   by running <code>"datalad get path/to/directory/or/file"</code>.
+   This command will trigger a download of the files, directories, or
+   subdatasets you have specified.<br><br>
+
+   More information on DataLad and how to use it can be found in the DataLad
+   Handbook at https://handbook.datalad.org/index.html. The chapter "DataLad
+   datasets" can help you to familiarize yourself with the concept of a dataset.
+
+
+
 .. admonition:: HELP! I'm new to this!
 
    If this is your reaction to reading the words DataLad dataset, sibling, or dataset publishing,  please head over to the `DataLad Handbook`_ for an introduction to DataLad.

requirements-devel.txt

@@ -4,3 +4,4 @@ pytest-cov
 coverage
 sphinx
 sphinx_rtd_theme
+sphinx-copybutton