From 220d14a7d18513cc79019af8526e883df9f439c2 Mon Sep 17 00:00:00 2001 From: Chenying Zhao Date: Thu, 26 Oct 2023 17:29:21 -0400 Subject: [PATCH 1/3] add to docs: what if babs-check-setup fails --- docs/source/babs-check-setup.rst | 46 +++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/source/babs-check-setup.rst b/docs/source/babs-check-setup.rst index 1d80de0a..ef23557f 100644 --- a/docs/source/babs-check-setup.rst +++ b/docs/source/babs-check-setup.rst @@ -18,7 +18,11 @@ Command-Line Arguments Detailed description ********************** -`babs-check-setup` will perform these steps: +-------------------------------------------------------------------- +What does ``babs-check-setup`` do? +-------------------------------------------------------------------- + +``babs-check-setup`` will perform these steps: 1. Print out configurations of the BABS project; 2. Perform sanity checks in this BABS project; @@ -26,6 +30,46 @@ Detailed description are installed in the designated environment. This happen when ``--job-test`` is requested. We highly recommend doing so. +--------------------------------------------------------------------------------------- +What if ``babs-check-setup`` fails or the BABS project's setup is not what I desire? +--------------------------------------------------------------------------------------- + +If running ``babs-check-setup`` (e.g., with test jobs) fails, +or the summarized information from ``babs-check-setup`` is not what you desire, +please remove the current BABS project, fix the problems, and generate a new BABS project. +In details, + +#. Before removing the current BABS project, make sure you know what went wrong and what to fix. + Please carefully read the printed messages from failed ``babs-check-setup``. + +#. Remove the current BABS project + with following commands:: + + cd /analysis # replace `` with the path to your BABS project + + # Remove input dataset(s) one by one: + datalad remove -d inputs/data/ # replace `` with each input dataset's name + # repeat above step until all input datasets have been removed. + # if above command leads to "drop impossible" due to modified content, add `--reckless modification` at the end + + git annex dead here + datalad push --to input + datalad push --to output + + cd .. + pwd # this prints ``; you can copy it in case you forgot + cd .. # outside of `` + rm -rf + + If you don't remove the current BABS project, you cannot overwrite it by running ``babs-init`` again. + + .. developer's note: above step: copied from `babs-init.rst` (CLI for ``babs-init``) + +#. Fix the problems, e.g., in the ``babs-init`` command, + or in the container configuration YAML file. + +#. Generate a new BABS project by running ``babs-init``. + ********************** Example commands ********************** From dd77c46a7df1a9c8cf361baa1ea15297e30f0ba1 Mon Sep 17 00:00:00 2001 From: Chenying Zhao Date: Thu, 26 Oct 2023 17:42:26 -0400 Subject: [PATCH 2/3] add sphinx_rtd_theme to doc of setup.cfg --- setup.cfg | 1 + 1 file changed, 1 insertion(+) diff --git a/setup.cfg b/setup.cfg index c68fda9f..288e627a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -50,6 +50,7 @@ doc = jinja2<3.1.0 # to fix the issue re: jinja2 docutils <0.17 # to fix the issue of bullet points not rendered sphinx_design # for adding in-line badges etc + sphinx_rtd_theme # needed by readthedocs tests = pytest pytest-xdist # for running pytest in parallel From 1b1eb367c5177e09b81b4f80c20ff52e0bb54a82 Mon Sep 17 00:00:00 2001 From: Chenying Zhao Date: Thu, 26 Oct 2023 18:47:16 -0400 Subject: [PATCH 3/3] update docs: can directly use the path to output ria as BABS input --- docs/source/preparation_input_dataset.rst | 37 +++++++++++++++++------ 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/docs/source/preparation_input_dataset.rst b/docs/source/preparation_input_dataset.rst index 194b2253..46394f72 100644 --- a/docs/source/preparation_input_dataset.rst +++ b/docs/source/preparation_input_dataset.rst @@ -78,21 +78,40 @@ See also Notes in ``babs-init`` CLI: :ref:`how-to-define-name-of-input-dataset` -================================================================ -Using results from another BABS project as input BIDS dataset -================================================================ -If you hope to use zipped results from another BABS' project ("BABS project A") -as input dataset for your current BABS project ("BABS project B"), you may: +================================================================== +Using results from another BABS project as an input BIDS dataset +================================================================== +If you hope to use zipped results from another BABS project ("BABS project A") +as input dataset for a new BABS project ("BABS project B"), you may follow these steps: -#. Clone the results out from the output RIA of BABS project A: +#. Test out the path you'll to use. + This step is optional but highly recommended. + This is to make sure that the input dataset's path you'll provide is correct. + To do so, please try cloning the results from the output RIA of BABS project A: * If BABS project A is on the local file system that current directory has access to, - you may clone its output RIA by:: + you may clone the results from its output RIA by:: datalad clone ria+file:///absolute/path/to/my_BABS_project_A/output_ria#~data - * For more details and/or other RIA scenarios, please refer to `datalad clone's documentation `_ and `DataLad Handbook about cloning from RIA stores `_ -#. Then use the path to the cloned dataset as the input dataset directory. + * For more details and/or other RIA scenarios, + please refer to `datalad clone's documentation `_ + and `DataLad Handbook about cloning from RIA stores `_ + +#. If you successfully cloned the results, then this means the path you used is correct. + You can go ahead and use this path + as the input dataset path for generating BABS project B. + + * Please make sure you use the *entire* string after ``datalad clone`` as the input dataset path. + For above example, this path is:: + + ria+file:///absolute/path/to/my_BABS_project_A/output_ria#~data + +#. You may remove the cloned results + of the BABS project A (from the first step):: + + datalad remove -d + #. :octicon:`alert-fill` :bdg-warning:`warning` Please refer to docs listed below for detailed requirements before you run ``babs-init``: