Merge pull request #146 from PennLINC/docs/paper_revision

[DOCS] update docs during paper revision

docs/source/babs-check-setup.rst

@@ -18,14 +18,58 @@ 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;
 3. Submit a test job to make sure necessary packages (e.g., `DataLad`)
    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 <project_root>/analysis    # replace `<project_root>` with the path to your BABS project
+
+    # Remove input dataset(s) one by one:
+    datalad remove -d inputs/data/<input_ds_name>   # replace `<input_ds_name>` 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 `<project_root>`; you can copy it in case you forgot
+    cd ..   # outside of `<project_root>`
+    rm -rf <project_root>
+
+   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
 **********************

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 <https://docs.datalad.org/en/stable/generated/man/datalad-clone.html>`_ and `DataLad Handbook about cloning from RIA stores <https://handbook.datalad.org/en/latest/beyond_basics/101-147-riastores.html#cloning-and-updating-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 <https://docs.datalad.org/en/stable/generated/man/datalad-clone.html>`_
+      and `DataLad Handbook about cloning from RIA stores <https://handbook.datalad.org/en/latest/beyond_basics/101-147-riastores.html#cloning-and-updating-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 <cloned_results_of_BABS_project_A>
+
 #. :octicon:`alert-fill` :bdg-warning:`warning`
    Please refer to docs listed below for detailed requirements before you run ``babs-init``:
 

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