Merge branch 'main' of github.com:datalad-handbook/book into print

datalad-handbook · Nov 1, 2023 · 685a964 · 685a964
2 parents 76ac99e + 464ee94
commit 685a964
Show file tree

Hide file tree

Showing 195 changed files with 462 additions and 919 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 [![Build status](https://ci.appveyor.com/api/projects/status/v8o167109n3irf5c/branch/main?svg=true)](https://ci.appveyor.com/project/mih/book/branch/main)
 [![Monthly link check](https://github.com/datalad-handbook/book/actions/workflows/linkcheck.yml/badge.svg)](https://github.com/datalad-handbook/book/actions/workflows/linkcheck.yml)
-[![Documentation Status](https://readthedocs.org/projects/datalad-handbook/badge/?version=latest)](http://handbook.datalad.org/en/latest/?badge=latest)
+[![Documentation Status](https://readthedocs.org/projects/datalad-handbook/badge/?version=latest)](https://handbook.datalad.org/en/latest/?badge=latest)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3608611.svg)](https://doi.org/10.5281/zenodo.3608611)
 [![made-with-datalad](https://www.datalad.org/badges/made_with.svg)](https://datalad.org)
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

diff --git a/artwork/OHBM_2020.svg b/artwork/OHBM_2020.svg
diff --git a/docs/basics/101-123-config2.rst b/docs/basics/101-123-config2.rst
@@ -148,7 +148,7 @@ There is one right in the root of your dataset:
    $ cat .gitmodules
 
 Based on these contents, you might have already guessed what this file
-stores. ``.gitmodules`` is a configuration file that stores the mapping between
+stores. The ``.gitmodules`` file is a configuration file that stores the mapping between
 your own dataset and any subdatasets you have installed in it.
 There will be an entry for each submodule (subdataset) in your dataset.
 The name *submodule* is Git terminology, and describes a Git repository inside of
@@ -257,7 +257,7 @@ Here is the directory structure:
       add (ok: 2)
       save (ok: 1)
 
-Now, we can apply the ``datalad-recursiveinstall`` configuration to skip recursive installations for subds1
+Now, we can apply the ``datalad-recursiveinstall`` configuration to skip recursive installations for ``subds1``
 
 .. code-block:: bash
 
@@ -475,7 +475,7 @@ This has been an intense lecture, you have to admit. One definite
 take-away from it has been that you now know a second reason why the hidden
 ``.git`` and ``.datalad`` directory contents and also the contents of ``.gitmodules`` and
 ``.gitattributes`` should not be carelessly tampered with -- they contain all of
-the repositories configurations.
+the repository's configurations.
 
 But you now also know how to modify these configurations with enough
 care and background knowledge such that nothing should go wrong once you

diff --git a/docs/basics/101-125-summary.rst b/docs/basics/101-125-summary.rst
@@ -14,7 +14,7 @@ your horizon about configurations of datasets:
   ``.datalad/config`` that apply to a specific dataset, but are committed and
   therefore distributed. More specialized scopes take precedence over more global scopes.
 
-- Almost all configurations can be set with the :gitcmd:`config`.
+- Almost all configurations can be set with the :gitcmd:`config` command.
   Its structure looks like this:
 
   .. code-block:: bash
@@ -32,7 +32,7 @@ your horizon about configurations of datasets:
   in a :gitcmd:`config` command.
 
 - The ``.gitattributes`` file is the only configuration file the :gitcmd:`config`
-  can not write to, because it has a different layout. However, run-procedures or
+  command can not write to, because it has a different layout. However, run-procedures or
   the user can write simple rules into it that determine which files are annexed
   and which are stored in Git.
 

diff --git a/docs/basics/101-130-yodaproject.rst b/docs/basics/101-130-yodaproject.rst
@@ -341,7 +341,7 @@ To compute the analysis you create the following Python script inside of ``code/
 .. runrecord:: _examples/DL-101-130-107
    :language: console
    :workdir: dl-101/DataLad-101/midterm_project
-   :emphasize-lines: 11-13, 23, 42
+   :emphasize-lines: 11-13, 23, 43
    :cast: 10_yoda
    :notes: Let's create code for an analysis
 
@@ -485,7 +485,7 @@ re-execution with :dlcmd:`rerun` easy.
    - `seaborn <https://seaborn.pydata.org>`_
    - `sklearn <https://scikit-learn.org>`_
 
-   The packages can be installed via ``pip`` [#f3]_.
+   The packages can be installed via :term:`pip`.
    However, if you do not want to install any
    Python packages, do not execute the remaining code examples in this section
    -- an upcoming section on ``datalad containers-run`` will allow you to
@@ -674,8 +674,7 @@ configuration, or interactively).
 
 .. importantnote:: Generate a GitHub token
 
-   GitHub `deprecated user-password authentication <https://developer.github.com/changes/2020-02-14-deprecating-password-auth>`_ supports authentication via personal access token only.
-
+   GitHub `deprecated user-password authentication <https://developer.github.com/changes/2020-02-14-deprecating-password-auth>`_ and instead supports authentication via personal access token.
    To ensure successful authentication, don't supply your password, but create a personal access token at `github.com/settings/tokens <https://github.com/settings/tokens>`_ [#f6]_ instead, and either
 
    * supply the token with the argument ``--github-login <TOKEN>`` from the command line,
@@ -943,8 +942,4 @@ On the looks and feels of a published dataset
 .. [#f5]  Alternatively, if you were to use DataLad's Python API, you could import and expose it as ``dl.<COMMAND>`` and ``dl.get()`` the relevant files. This however, would not record them as provenance in the dataset's history.
 
 .. [#f6] Instead of using GitHub's WebUI you could also obtain a token using the command line GitHub interface (https://github.com/sociomantic-tsunami/git-hub) by running ``git hub setup`` (if no 2FA is used).
-         If you decide to use the command line interface, here is help on how to use it:
-         Clone the `GitHub repository <https://github.com/sociomantic-tsunami/git-hub>`_ to your local computer.
-         Decide whether you want to build a Debian package to install, or install the single-file Python script distributed in the repository.
-         Make sure that all `requirements <https://github.com/sociomantic-tsunami/git-hub>`_ for your preferred version are installed , and run either ``make deb`` followed by ``sudo dpkg -i deb/git-hub*all.deb``, or ``make install``.
 
diff --git a/docs/basics/101-139-hostingservices.rst b/docs/basics/101-139-hostingservices.rst
@@ -357,6 +357,6 @@ Once you have set up your dataset sibling(s), you can push individual datasets w
          is protecting. If the private key does not have a passphrase, simply copying
          this file grants a person access!
 
-.. [#f3]  GitHub `deprecated user-password authentication <https://developer.github.com/changes/2020-02-14-deprecating-password-auth>`_ and only supports authentication via personal access token from November 13th 2020 onwards. Supplying a password instead of a token will fail to authenticate.
+.. [#f3]  GitHub `deprecated user-password authentication <https://developer.github.com/changes/2020-02-14-deprecating-password-auth>`_ in favor of authentication via personal access token. Supplying a password instead of a token will fail to authenticate.
 
 .. [#f4] The default project name ``project`` and path separator ``-`` are configurable using the dataset-level configurations ``datalad.gitlab-default-projectname`` and ``datalad.gitlab-default-pathseparator``
diff --git a/docs/basics/_examples/DL-101-101-101 b/docs/basics/_examples/DL-101-101-101
@@ -4,6 +4,3 @@ $ datalad create -c text2git DataLad-101
 [INFO] == Command exit (modification check follows) =====
 run(ok): /home/me/dl-101/DataLad-101 (dataset) [VIRTUALENV/bin/python /home/a...]
 create(ok): /home/me/dl-101/DataLad-101 (dataset)
-action summary:
-  create (ok: 1)
-  run (ok: 1)
diff --git a/docs/basics/_examples/DL-101-102-106 b/docs/basics/_examples/DL-101-102-106
@@ -2,6 +2,3 @@ $ datalad save -m "add books on Python and Unix to read later"
 add(ok): books/TLCL.pdf (file)
 add(ok): books/byte-of-python.pdf (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 2)
-  save (ok: 1)
diff --git a/docs/basics/_examples/DL-101-102-107 b/docs/basics/_examples/DL-101-102-107
@@ -1,5 +1,5 @@
 $ git log -p -n 1
-commit d2bb1a86✂SHA1
+commit b40316a6✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -15,9 +15,9 @@ index 0000000..4c84b61
 \ No newline at end of file
 diff --git a/books/byte-of-python.pdf b/books/byte-of-python.pdf
 new file mode 120000
-index 0000000..b9fcbff
+index 0000000..7a6e51e
 --- /dev/null
 +++ b/books/byte-of-python.pdf
 @@ -0,0 +1 @@
-+../.git/annex/objects/P5/qK/✂/MD5E-s2693891--e61afe4b✂MD5.pdf
++../.git/annex/objects/xF/42/✂/MD5E-s4161086--c832fc13✂MD5.pdf
 \ No newline at end of file
diff --git a/docs/basics/_examples/DL-101-102-110 b/docs/basics/_examples/DL-101-102-110
@@ -1,6 +1,3 @@
 $ datalad save -m "add reference book about git" books/progit.pdf
 add(ok): books/progit.pdf (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 1)
-  save (ok: 1)
diff --git a/docs/basics/_examples/DL-101-102-111 b/docs/basics/_examples/DL-101-102-111
@@ -1,6 +1,6 @@
 # lets make the output a bit more concise with the --oneline option
 $ git log --oneline
-8e5dc80 add reference book about git
-d2bb1a8 add books on Python and Unix to read later
+a875e49 add reference book about git
+b40316a add books on Python and Unix to read later
 e0ff3a7 Instruct annex to add text files to Git
 4ce681d [DATALAD] new dataset
diff --git a/docs/basics/_examples/DL-101-102-112 b/docs/basics/_examples/DL-101-102-112
@@ -7,7 +7,3 @@ $ datalad download-url \
 download_url(ok): /home/me/dl-101/DataLad-101/books/bash_guide.pdf (file)
 add(ok): books/bash_guide.pdf (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 1)
-  download_url (ok: 1)
-  save (ok: 1)
diff --git a/docs/basics/_examples/DL-101-102-115 b/docs/basics/_examples/DL-101-102-115
@@ -1,5 +1,5 @@
 $ git log -p -n 1
-commit bcb0ffe8✂SHA1
+commit 59ac8d32✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 

diff --git a/docs/basics/_examples/DL-101-102-116 b/docs/basics/_examples/DL-101-102-116
@@ -1,6 +1,6 @@
 $ git log --oneline
-bcb0ffe add beginners guide on bash
-8e5dc80 add reference book about git
-d2bb1a8 add books on Python and Unix to read later
+59ac8d3 add beginners guide on bash
+a875e49 add reference book about git
+b40316a add books on Python and Unix to read later
 e0ff3a7 Instruct annex to add text files to Git
 4ce681d [DATALAD] new dataset
diff --git a/docs/basics/_examples/DL-101-103-103 b/docs/basics/_examples/DL-101-103-103
@@ -1,6 +1,3 @@
 $ datalad save -m "Add notes on datalad create"
 add(ok): notes.txt (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 1)
-  save (ok: 1)
diff --git a/docs/basics/_examples/DL-101-103-106 b/docs/basics/_examples/DL-101-103-106
@@ -1,6 +1,3 @@
 $ datalad save -m "add note on datalad save"
 add(ok): notes.txt (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 1)
-  save (ok: 1)
diff --git a/docs/basics/_examples/DL-101-103-107 b/docs/basics/_examples/DL-101-103-107
@@ -1,5 +1,5 @@
 $ git log -p -n 2
-commit 9783a90c✂SHA1
+commit e310b465✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -18,7 +18,7 @@ index 3a7a1fe..0142412 100644
 +Note to self: Always use informative, concise commit messages.
 +
 
-commit b538dae3✂SHA1
+commit 874d766f✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 

diff --git a/docs/basics/_examples/DL-101-105-102 b/docs/basics/_examples/DL-101-105-102
@@ -1,20 +1,10 @@
 $ datalad clone --dataset . \
  https://github.com/datalad-datasets/longnow-podcasts.git recordings/longnow
 [INFO] Attempting a clone into /home/me/dl-101/DataLad-101/recordings/longnow
-[INFO] Attempting to clone from https://github.com/datalad-datasets/longnow-podcasts.git to /home/me/dl-101/DataLad-101/recordings/longnow
-[INFO] Start enumerating objects
-[INFO] Start receiving objects
-[INFO] Start resolving deltas
-[INFO] Completed clone attempts for Dataset(/home/me/dl-101/DataLad-101/recordings/longnow)
 [INFO] Remote origin not usable by git-annex; setting annex-ignore
-[INFO] https://github.com/datalad-datasets/longnow-podcasts.git/config download failed: Not Found
 install(ok): recordings/longnow (dataset)
 add(ok): recordings/longnow (dataset)
 add(ok): .gitmodules (file)
 save(ok): . (dataset)
 add(ok): .gitmodules (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 3)
-  install (ok: 1)
-  save (ok: 2)
diff --git a/docs/basics/_examples/DL-101-105-115 b/docs/basics/_examples/DL-101-105-115
@@ -10,6 +10,3 @@ EOT
 $ datalad save -m "Add note on datalad clone"
 add(ok): notes.txt (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 1)
-  save (ok: 1)
diff --git a/docs/basics/_examples/DL-101-106-101 b/docs/basics/_examples/DL-101-106-101
@@ -1,5 +1,5 @@
 $ git log -p -n 3
-commit fa63a083✂SHA1
+commit 87609a36✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -19,7 +19,7 @@ index 0142412..e34ef1f 100644
 +superdataset with the '-d' option.
 +
 
-commit 7c489fbf✂SHA1
+commit 3c016f73✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -44,7 +44,7 @@ index 0000000..dcc34fb
 @@ -0,0 +1 @@
 +Subproject commit dcc34fbe✂SHA1
 
-commit 9783a90c✂SHA1
+commit e310b465✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -63,7 +63,7 @@ index 3a7a1fe..0142412 100644
 +Note to self: Always use informative, concise commit messages.
 +
 
-commit b538dae3✂SHA1
+commit 874d766f✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -79,7 +79,7 @@ index 0000000..3a7a1fe
 +The dataset is created empty
 +
 
-commit bcb0ffe8✂SHA1
+commit 59ac8d32✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -94,7 +94,7 @@ index 0000000..00ca6bd
 +../.git/annex/objects/WF/Gq/✂/MD5E-s1198170--0ab2c121✂MD5.pdf
 \ No newline at end of file
 
-commit 8e5dc808✂SHA1
+commit a875e496✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -109,7 +109,7 @@ index 0000000..c5d2ab2
 +../.git/annex/objects/G6/Gj/✂/MD5E-s12465653--05cd7ed5✂MD5.pdf
 \ No newline at end of file
 
-commit d2bb1a86✂SHA1
+commit b40316a6✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
@@ -125,11 +125,11 @@ index 0000000..4c84b61
 \ No newline at end of file
 diff --git a/books/byte-of-python.pdf b/books/byte-of-python.pdf
 new file mode 120000
-index 0000000..b9fcbff
+index 0000000..7a6e51e
 --- /dev/null
 +++ b/books/byte-of-python.pdf
 @@ -0,0 +1 @@
-+../.git/annex/objects/P5/qK/✂/MD5E-s2693891--e61afe4b✂MD5.pdf
++../.git/annex/objects/xF/42/✂/MD5E-s4161086--c832fc13✂MD5.pdf
 \ No newline at end of file
 
 commit e0ff3a73✂SHA1

diff --git a/docs/basics/_examples/DL-101-108-104 b/docs/basics/_examples/DL-101-108-104
@@ -1,6 +1,3 @@
 $ datalad save -m "Add short script to write a list of podcast speakers and titles"
 add(ok): code/list_titles.sh (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 1)
-  save (ok: 1)
diff --git a/docs/basics/_examples/DL-101-108-106 b/docs/basics/_examples/DL-101-108-106
@@ -1,5 +1,5 @@
 $ git log -p -n 1   # On Windows, you may just want to type "git log".
-commit f4f30396✂SHA1
+commit e37c9fc9✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 

diff --git a/docs/basics/_examples/DL-101-108-108 b/docs/basics/_examples/DL-101-108-108
@@ -1,12 +1,12 @@
 $ git log --oneline
-f4f3039 [DATALAD RUNCMD] create a list of podcast titles
-50addd7 Add short script to write a list of podcast speakers and titles
-fa63a08 Add note on datalad clone
-7c489fb [DATALAD] Added subdataset
-9783a90 add note on datalad save
-b538dae Add notes on datalad create
-bcb0ffe add beginners guide on bash
-8e5dc80 add reference book about git
-d2bb1a8 add books on Python and Unix to read later
+e37c9fc [DATALAD RUNCMD] create a list of podcast titles
+e799b6b Add short script to write a list of podcast speakers and titles
+87609a3 Add note on datalad clone
+3c016f7 [DATALAD] Added subdataset
+e310b46 add note on datalad save
+874d766 Add notes on datalad create
+59ac8d3 add beginners guide on bash
+a875e49 add reference book about git
+b40316a add books on Python and Unix to read later
 e0ff3a7 Instruct annex to add text files to Git
 4ce681d [DATALAD] new dataset
diff --git a/docs/basics/_examples/DL-101-109-104 b/docs/basics/_examples/DL-101-109-104
@@ -2,6 +2,3 @@ $ datalad save -m "BF: list both directories content" \
   code/list_titles.sh
 add(ok): code/list_titles.sh (file)
 save(ok): . (dataset)
-action summary:
-  add (ok: 1)
-  save (ok: 1)
diff --git a/docs/basics/_examples/DL-101-109-105 b/docs/basics/_examples/DL-101-109-105
@@ -1,11 +1,11 @@
 $ git log -n 2
-commit 07db512b✂SHA1
+commit f7ea9f3d✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000
 
     BF: list both directories content
 
-commit f4f30396✂SHA1
+commit e37c9fc9✂SHA1
 Author: Elena Piscopia <elena@example.net>
 Date:   Tue Jun 18 16:13:00 2019 +0000