From 5b51def582d1b4d82043a4e7acd9307ff522e345 Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Thu, 9 Nov 2023 09:36:44 +0100 Subject: [PATCH 1/3] turn 'hidden section' references into find-out-more refs --- docs/basics/101-101-create.rst | 1 + docs/basics/101-115-symlinks.rst | 2 +- docs/basics/101-116-sharelocal.rst | 3 +-- docs/basics/101-123-config2.rst | 2 +- docs/basics/101-132-advancednesting.rst | 4 ++-- docs/basics/101-133-containersrun.rst | 4 ++-- docs/basics/101-136-filesystem.rst | 8 ++++---- docs/beyond_basics/101-146-providers.rst | 3 ++- docs/beyond_basics/101-147-riastores.rst | 2 +- docs/beyond_basics/101-161-biganalyses.rst | 2 +- docs/beyond_basics/101-179-gitignore.rst | 4 ++-- docs/usecases/HCP_dataset.rst | 4 ++-- 12 files changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/basics/101-101-create.rst b/docs/basics/101-101-create.rst index c543d376f..ae8dc58dc 100644 --- a/docs/basics/101-101-create.rst +++ b/docs/basics/101-101-create.rst @@ -34,6 +34,7 @@ Note the command structure of :dlcmd:`create` (optional bits are enclosed in ``[ .. index:: pair: set description for dataset location; with DataLad .. find-out-more:: What is the description option of 'datalad create'? + :name: fom-create-description The optional ``--description`` flag allows you to provide a short description of the *location* of your dataset, for example with diff --git a/docs/basics/101-115-symlinks.rst b/docs/basics/101-115-symlinks.rst index 083f7dd58..bfada4380 100644 --- a/docs/basics/101-115-symlinks.rst +++ b/docs/basics/101-115-symlinks.rst @@ -140,7 +140,7 @@ This comes with two very important advantages: One, should you have copies of the same data in different places of your dataset, the symlinks of these files point to the same place (in order to understand why this is the case, you -will need to read the hidden section at the end of the page). +will need to read the :find-out-more:`about the object tree `). Therefore, any amount of copies of a piece of data is only one single piece of data in your object tree. This, depending on how much identical file content lies in different parts of your dataset, diff --git a/docs/basics/101-116-sharelocal.rst b/docs/basics/101-116-sharelocal.rst index c3ac9ed0b..b63397718 100644 --- a/docs/basics/101-116-sharelocal.rst +++ b/docs/basics/101-116-sharelocal.rst @@ -194,8 +194,7 @@ and hostname of your computer. "This", you exclaim, excited about your own reali pair: set description for dataset location; with DataLad .. find-out-more:: What is this location, and what if I provided a description? - Back in the very first section of the Basics, :ref:`createDS`, a hidden - section mentioned the ``--description`` option of :dlcmd:`create`. + Back in the very first section of the Basics, :ref:`createDS`, a :find-out-more:`mentioned the '--description' option ` of :dlcmd:`create`. With this option, you can provide a description about the dataset *location*. The :gitannexcmd:`whereis` command, finally, is where such a description diff --git a/docs/basics/101-123-config2.rst b/docs/basics/101-123-config2.rst index f05dacaa2..c8ed19eff 100644 --- a/docs/basics/101-123-config2.rst +++ b/docs/basics/101-123-config2.rst @@ -34,7 +34,7 @@ This looks neither spectacular nor pretty. Also, it does not follow the ``sectio organization of the ``.git/config`` file anymore. Instead, there are three lines, and all of these seem to have something to do with the configuration of git-annex. There even is one key word that you recognize: MD5E. -If you have read the hidden section in :ref:`symlink` +If you have read the :find-out-more:`on object trees ` you will recognize it as a reference to the type of key used by git-annex to identify and store file content in the object-tree. The first row, ``* annex.backend=MD5E``, therefore translates to "Everything in this diff --git a/docs/basics/101-132-advancednesting.rst b/docs/basics/101-132-advancednesting.rst index f17e48b4f..775f487c7 100644 --- a/docs/basics/101-132-advancednesting.rst +++ b/docs/basics/101-132-advancednesting.rst @@ -123,7 +123,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore `. Note that both of these commands return only the ``untracked`` file and not not the ``modified`` subdataset because we're explicitly querying only the subdataset for its status. - If you however, as done outside of this hidden section, you want to know about + If you however, as done outside of this Find-out-more, you want to know about the subdataset record in the superdataset without causing a status query for the state *within* the subdataset itself, you can also provide an explicit path to the dataset (without a trailing path separator). This can be used @@ -171,7 +171,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore `. option (especially powerful when combined with ``-f json_pp``). To get a complete overview on what you could do, check out the technical documentation of :dlcmd:`status` `here `_. - Before we leave this hidden section, lets undo the modification of the subdataset + Before we leave this Find-out-more, lets undo the modification of the subdataset by removing the untracked file: .. runrecord:: _examples/DL-101-132-109 diff --git a/docs/basics/101-133-containersrun.rst b/docs/basics/101-133-containersrun.rst index 036cc1783..17d739ceb 100644 --- a/docs/basics/101-133-containersrun.rst +++ b/docs/basics/101-133-containersrun.rst @@ -143,12 +143,12 @@ For this, we will pull an image from Singularity hub. This image was made for the handbook, and it contains the relevant Python setup for the analysis. Its recipe lives in the handbook's `resources repository `_. -If you're curious how to create a Singularity image, the hidden -section below has some pointers: +If you're curious how to create a Singularity image, the :find-out-more:`on this topic ` has some pointers: .. index:: pair: build container image; with Singularity .. find-out-more:: How to make a Singularity image + :name: fom-container-creation Singularity containers are build from image files, often called "recipes", that hold a "definition" of the software container and its diff --git a/docs/basics/101-136-filesystem.rst b/docs/basics/101-136-filesystem.rst index 915a11906..ba67d7e34 100644 --- a/docs/basics/101-136-filesystem.rst +++ b/docs/basics/101-136-filesystem.rst @@ -110,12 +110,12 @@ save a change that is marked as a deletion in a datalad save -m "rename file" oldname newname Alternatively, there is also a way to save the name change -only using Git tools only, outlined in the following hidden -section. If you are a Git user, you will be very familiar with it. +only using Git tools only, outlined in the :find-out-more:`on faster renaming `. If you are a Git user, you will be very familiar with it. .. index:: pair: rename file; with Git .. find-out-more:: Faster renaming with Git tools + :name: fom-gitmv Git has built-in commands that provide a solution in two steps. @@ -757,12 +757,12 @@ use. Beware of one thing though: If your dataset either is a sibling or has a sibling with the source being a path, moving or renaming the dataset will break the linkage between the datasets. This can -be fixed easily though. We can try this in the following hidden -section. +be fixed easily though. We can try this in the :find-out-more:`on adjusting sibling URLs `. .. index:: pair: move subdataset; with Git .. find-out-more:: If a renamed/moved dataset is a sibling... + :name: fom-adjust-sibling-urls As section :ref:`config` explains, each sibling is registered in ``.git/config`` in a "submodule" section. diff --git a/docs/beyond_basics/101-146-providers.rst b/docs/beyond_basics/101-146-providers.rst index c5d902ea5..fb6b78e85 100644 --- a/docs/beyond_basics/101-146-providers.rst +++ b/docs/beyond_basics/101-146-providers.rst @@ -62,7 +62,7 @@ dataset -- lacks a configuration for data access about this server:: However, data access can be configured by the user if the required authentication and credential type are supported by -DataLad (a list is given in the hidden section below). +DataLad (a list is given in the :find-out-more:`on authentication `). With a data access configuration in place, commands such as :dlcmd:`download-url` or :dlcmd:`addurls` can work with urls the point to the location of the data to be retrieved, and @@ -82,6 +82,7 @@ The following information is needed: The example below sheds some light one this. .. find-out-more:: Which authentication and credential types are possible? + :name: fom-provider-auth When configuring custom data access, credential and authentication type are required information. Below, we list the most common choices for these fields. diff --git a/docs/beyond_basics/101-147-riastores.rst b/docs/beyond_basics/101-147-riastores.rst index 1c2366764..e6af091dc 100644 --- a/docs/beyond_basics/101-147-riastores.rst +++ b/docs/beyond_basics/101-147-riastores.rst @@ -708,7 +708,7 @@ procedures. `the docs `_. .. [#f3] To re-read about how git-annex's object tree works, check out section - :ref:`symlink`, and pay close attention to the hidden section. + :ref:`symlink`, and pay close attention to the :find-out-more:`on the object tree `. Additionally, you can find a lot of background information in git-annex's `documentation `_. diff --git a/docs/beyond_basics/101-161-biganalyses.rst b/docs/beyond_basics/101-161-biganalyses.rst index 17a17ddd8..02225707a 100644 --- a/docs/beyond_basics/101-161-biganalyses.rst +++ b/docs/beyond_basics/101-161-biganalyses.rst @@ -138,7 +138,7 @@ in size even if they are each small in size. .. [#f1] FEAT is a software tool for model-based fMRI data analysis and part of of `FSL `_. -.. [#f2] Read more about DataLad's Python API in the first hidden section in +.. [#f2] Read more about DataLad's Python API in the :find-out-more:`on it ` in :ref:`yoda_project`. .. [#f3] Read up on these configurations in the chapter :ref:`chapter_config`. diff --git a/docs/beyond_basics/101-179-gitignore.rst b/docs/beyond_basics/101-179-gitignore.rst index 46c7de0bc..33b4ac9c0 100644 --- a/docs/beyond_basics/101-179-gitignore.rst +++ b/docs/beyond_basics/101-179-gitignore.rst @@ -67,8 +67,7 @@ or create your own one. To specify dataset content to be git-ignored, you can either write a full file name, e.g. ``playlists/my-little-pony-themesongs/Friendship-is-magic.mp3`` into this file, or paths or patterns that make use of globbing, such as -``playlists/my-little-pony-themesongs/*``. The hidden section at the end of this -page contains some general rules for patterns in ``.gitignore`` files. Afterwards, +``playlists/my-little-pony-themesongs/*``. The :find-out-more:`on general rules for patterns in .gitignore files ` contains a helpful overview. Afterwards, you just need to save the file once to your dataset so that it is version controlled. If you have new content you do not want to track, you can add new paths or patterns to the file, and save these modifications. @@ -120,6 +119,7 @@ ignored! Therefore, a ``.gitignore`` file can give you a space inside of your dataset to be messy, if you want to be. .. find-out-more:: Rules for .gitignore files + :name: fom-gitignore Here are some general rules for the patterns you can put into a ``.gitignore`` file, taken from the book `Pro Git `_ : diff --git a/docs/usecases/HCP_dataset.rst b/docs/usecases/HCP_dataset.rst index a7ec0394e..5d533a940 100644 --- a/docs/usecases/HCP_dataset.rst +++ b/docs/usecases/HCP_dataset.rst @@ -166,10 +166,10 @@ which it has been aggregated are small in size, and yet provide access to the HC data for anyone who has valid AWS S3 credentials. At the end of this step, there is one nested dataset per subject in the HCP data -release. If you are interested in the details of this process, checkout the -hidden section below. +release. If you are interested in the details of this process, checkout the :find-out-more:`on the datasets' generation `. .. find-out-more:: How exactly did the datasets came to be? + :name: fom-hcp All code and tables necessary to generate the HCP datasets can be found on GitHub at `github.com/TobiasKadelka/build_hcp `_. From b58e1d36e47100e6f4f554d210137c7dd62972f6 Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Thu, 9 Nov 2023 10:03:17 +0100 Subject: [PATCH 2/3] replace cross-page references to findoutmore's with regular :ref: machanism --- docs/basics/101-101-create.rst | 2 +- docs/basics/101-115-symlinks.rst | 1 + docs/basics/101-116-sharelocal.rst | 2 +- docs/basics/101-123-config2.rst | 2 +- docs/basics/101-130-yodaproject.rst | 1 + docs/beyond_basics/101-147-riastores.rst | 2 +- docs/beyond_basics/101-161-biganalyses.rst | 2 +- 7 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/basics/101-101-create.rst b/docs/basics/101-101-create.rst index ae8dc58dc..665ff6902 100644 --- a/docs/basics/101-101-create.rst +++ b/docs/basics/101-101-create.rst @@ -31,10 +31,10 @@ Note the command structure of :dlcmd:`create` (optional bits are enclosed in ``[ datalad create [--description "..."] [-c ] PATH +.. _createdescription: .. index:: pair: set description for dataset location; with DataLad .. find-out-more:: What is the description option of 'datalad create'? - :name: fom-create-description The optional ``--description`` flag allows you to provide a short description of the *location* of your dataset, for example with diff --git a/docs/basics/101-115-symlinks.rst b/docs/basics/101-115-symlinks.rst index bfada4380..3a7988001 100644 --- a/docs/basics/101-115-symlinks.rst +++ b/docs/basics/101-115-symlinks.rst @@ -171,6 +171,7 @@ moving, renaming, or copying content translate to dataset modifications in certain situations. Later in this book we will have a section on how to manage the file system in a DataLad dataset (:ref:`file system`). +.. _objecttree: .. index:: pair: key; git-annex concept .. find-out-more:: more about paths, checksums, object trees, and data integrity diff --git a/docs/basics/101-116-sharelocal.rst b/docs/basics/101-116-sharelocal.rst index b63397718..9dfc9fce2 100644 --- a/docs/basics/101-116-sharelocal.rst +++ b/docs/basics/101-116-sharelocal.rst @@ -194,7 +194,7 @@ and hostname of your computer. "This", you exclaim, excited about your own reali pair: set description for dataset location; with DataLad .. find-out-more:: What is this location, and what if I provided a description? - Back in the very first section of the Basics, :ref:`createDS`, a :find-out-more:`mentioned the '--description' option ` of :dlcmd:`create`. + Back in the very first section of the Basics, :ref:`createDS`, a :ref:`Find-out-more mentioned the '--description' option ` of :dlcmd:`create`. With this option, you can provide a description about the dataset *location*. The :gitannexcmd:`whereis` command, finally, is where such a description diff --git a/docs/basics/101-123-config2.rst b/docs/basics/101-123-config2.rst index c8ed19eff..a88f2b257 100644 --- a/docs/basics/101-123-config2.rst +++ b/docs/basics/101-123-config2.rst @@ -34,7 +34,7 @@ This looks neither spectacular nor pretty. Also, it does not follow the ``sectio organization of the ``.git/config`` file anymore. Instead, there are three lines, and all of these seem to have something to do with the configuration of git-annex. There even is one key word that you recognize: MD5E. -If you have read the :find-out-more:`on object trees ` +If you have read the :ref:`Find-out-more on object trees ` you will recognize it as a reference to the type of key used by git-annex to identify and store file content in the object-tree. The first row, ``* annex.backend=MD5E``, therefore translates to "Everything in this diff --git a/docs/basics/101-130-yodaproject.rst b/docs/basics/101-130-yodaproject.rst index e611dc89a..5cebbb7d7 100644 --- a/docs/basics/101-130-yodaproject.rst +++ b/docs/basics/101-130-yodaproject.rst @@ -14,6 +14,7 @@ the `Python `__ programming language, you decide to script your analysis in Python. Delighted, you find out that there is even a Python API for DataLad's functionality that you can read about in :ref:`a Findoutmore on DataLad in Python`. +.. _pythonapi: .. index:: pair: use DataLad API; with Python .. find-out-more:: DataLad's Python API diff --git a/docs/beyond_basics/101-147-riastores.rst b/docs/beyond_basics/101-147-riastores.rst index e6af091dc..f671edec4 100644 --- a/docs/beyond_basics/101-147-riastores.rst +++ b/docs/beyond_basics/101-147-riastores.rst @@ -708,7 +708,7 @@ procedures. `the docs `_. .. [#f3] To re-read about how git-annex's object tree works, check out section - :ref:`symlink`, and pay close attention to the :find-out-more:`on the object tree `. + :ref:`symlink`, and pay close attention to the :ref:`Find-out-more on the object tree `. Additionally, you can find a lot of background information in git-annex's `documentation `_. diff --git a/docs/beyond_basics/101-161-biganalyses.rst b/docs/beyond_basics/101-161-biganalyses.rst index 02225707a..afdac0b10 100644 --- a/docs/beyond_basics/101-161-biganalyses.rst +++ b/docs/beyond_basics/101-161-biganalyses.rst @@ -138,7 +138,7 @@ in size even if they are each small in size. .. [#f1] FEAT is a software tool for model-based fMRI data analysis and part of of `FSL `_. -.. [#f2] Read more about DataLad's Python API in the :find-out-more:`on it ` in +.. [#f2] Read more about DataLad's Python API in the :ref:`Find-out-more on it ` in :ref:`yoda_project`. .. [#f3] Read up on these configurations in the chapter :ref:`chapter_config`. From 477e55b1c7e2c99a1cc1a9d463715df2063bfb62 Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Thu, 9 Nov 2023 10:12:44 +0100 Subject: [PATCH 3/3] resolve references in brackets --- docs/basics/101-115-symlinks.rst | 4 ++-- docs/beyond_basics/101-146-providers.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/basics/101-115-symlinks.rst b/docs/basics/101-115-symlinks.rst index 3a7988001..de69a3470 100644 --- a/docs/basics/101-115-symlinks.rst +++ b/docs/basics/101-115-symlinks.rst @@ -139,8 +139,8 @@ This comes with two very important advantages: One, should you have copies of the same data in different places of your dataset, the symlinks of these files -point to the same place (in order to understand why this is the case, you -will need to read the :find-out-more:`about the object tree `). +point to the same place - in order to understand why this is the case, you +will need to read the :find-out-more:`about the object tree `. Therefore, any amount of copies of a piece of data is only one single piece of data in your object tree. This, depending on how much identical file content lies in different parts of your dataset, diff --git a/docs/beyond_basics/101-146-providers.rst b/docs/beyond_basics/101-146-providers.rst index fb6b78e85..4c5b74905 100644 --- a/docs/beyond_basics/101-146-providers.rst +++ b/docs/beyond_basics/101-146-providers.rst @@ -62,7 +62,7 @@ dataset -- lacks a configuration for data access about this server:: However, data access can be configured by the user if the required authentication and credential type are supported by -DataLad (a list is given in the :find-out-more:`on authentication `). +DataLad - a list is given in the :find-out-more:`on authentication `. With a data access configuration in place, commands such as :dlcmd:`download-url` or :dlcmd:`addurls` can work with urls the point to the location of the data to be retrieved, and