Merge pull request #148 from PennLINC/docs/nmind_silver

[DOCS] achieve more checks in NMIND docs domain at silver level

Author: Chenying Zhao

README.rst

@@ -19,9 +19,10 @@ BIDS App Bootstrap (BABS) is a reproducible, generalizable, and
 scalable Python package for BIDS App analysis of large datasets.
 It uses `DataLad <https://www.datalad.org/>`_ and adopts
 the `FAIRly big framework <https://doi.org/10.1038/s41597-022-01163-2>`_.
-Currently it is compatible with SGE and Slurm clusters.
+Currently, BABS supports jobs submissions and audits on Sun Grid Engine (SGE) and Slurm
+high performance computing (HPC) clusters.
 
-BABS functions
+BABS programs
 ---------------------
 
 .. image:: https://github.com/PennLINC/babs/raw/main/docs/source/_static/babs_cli.png
@@ -32,3 +33,19 @@ Schematic of BABS workflow
 ----------------------------
 .. image:: https://github.com/PennLINC/babs/raw/main/docs/source/_static/babs_workflow.png
 .. Note: this image is taken from the main branch, so it's normal that docs built from branches is not up-to-date.
+
+Background and Significance
+-------------------------------
+
+Neuroimaging research faces a crisis of reproducibility.
+With massive sample sizes and greater data complexity, this problem becomes more acute.
+The BIDS Apps - the software operating on BIDS data - have provided a substantial advance.
+However, even using BIDS Apps, a full audit trail of data processing is a necessary prerequisite for fully reproducible research.
+Obtaining a faithful record of the audit trail is challenging - especially for large datasets.
+Recently, the `FAIRly big framework <https://doi.org/10.1038/s41597-022-01163-2>`_
+was introduced as a way to facilitate reproducible processing of large-scale data
+by leveraging `DataLad <https://www.datalad.org/>`_ - a version control system for data management.
+However, the current implementation of this framework remains challenging to general users. 
+
+BABS was developed to address these challenges
+and to facilitate the reproducible application of BIDS Apps to large-scale datasets.

docs/source/index.rst

@@ -2,11 +2,14 @@
 .. include:: ../../README.rst
 .. include:: links.rst
 
-Documentations
+Documentation
 ==================
 
+Please follow the instructions in this documentation to use BABS.
+Currently there is no alternative usage of BABS.
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    overview
    installation

docs/source/installation.rst

@@ -4,6 +4,20 @@ Installation
 
 .. contents:: Table of Contents
 
+Step 0. System requirement
+=============================================
+
+Currently BABS supports applications on high performance computing (HPC) clusters,
+specifically, Sun Grid Engine (SGE) and Slurm clusters.
+Please make sure Singularity or one of its successors
+(i.e. SingularityCE or Apptainer which BABS currently supports) is available on the cluster.
+
+Currently, BABS is **not** compatible with:
+
+* cloud-based computing platforms (e.g., Amazon Web Services [AWS]);
+* local computers where a job scheduling system or Singularity software is not installed;
+* computing nodes without job scheduling systems.
+
 Step 1. Prepare a conda environment for BABS
 =============================================