add container doc

CHANGELOG.md

@@ -95,7 +95,7 @@ Congrats 🥳
 
 We could not be more proud of the 3.0.1 dcm2bids release 😊 . We put everything we've learned from our past experiences and listen to all our users' ideas into this version.
 
-Advanced searching criterias such as extractors combined with custom entities, the ability to compare floats or the auto_extract_entities option directly accessible from dcm2bids command will make the conversion to BIDS smoother than ever and significantly reduce the complexity and the length of your configuration file especially for multi-site acquisitions.
+Advanced searching criteria such as extractors combined with custom entities, the ability to compare floats or the auto_extract_entities option directly accessible from dcm2bids command will make the conversion to BIDS smoother than ever and significantly reduce the complexity and the length of your configuration file especially for multi-site acquisitions.
 
 We highly encourage you to dive into the [documentation](https://unfmontreal.github.io/Dcm2Bids/3.0.1) since we added quite a lot of new features.
 

README.md

@@ -48,7 +48,8 @@ Please take a look at the [documentation][dcm2bids-doc] to:
 
 * [Learn about bids][bids-spec] with some dataset [examples][bids-examples]
 * [Install dcm2bids][dcm2bids-install]
-* [Follow the tutorial][dcm2bids-tutorial]
+* [Use docker and Apptainer/Singularity][dcm2bids-container]
+* [Follow the tutorials][dcm2bids-tutorial]
 * [Seek for more advanced usage][dcm2bids-advanced]
 
 ## Issues and Questions
@@ -68,6 +69,7 @@ Before posting your question, you may want to first browse through questions tha
 [dcm2bids-install]: https://unfmontreal.github.io/Dcm2Bids/latest/get-started/install/
 [dcm2bids-tutorial]: https://unfmontreal.github.io/Dcm2Bids/latest/tutorial/first-steps/#tutorial-first-steps
 [dcm2bids-advanced]: https://unfmontreal.github.io/Dcm2Bids/latest/advanced/
+[dcm2bids-container]: https://unfmontreal.github.io/Dcm2Bids/latest/how-to/container/
 [dcm2bids-upgrade]: https://unfmontreal.github.io/Dcm2Bids/dev/upgrade/
 [dcm2bids-issues]: https://github.com/UNFmontreal/Dcm2Bids/issues
 [dcm2niix-install]: https://github.com/rordenlab/dcm2niix#install

docs/get-started/install.md

@@ -9,6 +9,19 @@ date: 2022-04-17
 
 There are several ways to install dcm2bids.
 
+## Containers
+
+We provide a container image that includes both dcm2niix and dcm2bids as well as pydeface and the BIDS validator.
+You can install it using [Docker][docker] or [Apptainer/Singularity][apptainer].
+
+=== "Docker"
+
+    `docker pull unfmontreal/dcm2bids:latest`
+
+=== "Apptainer/Singularity"
+
+    `singularity pull dcm2bids_latest.sif docker://unfmontreal/dcm2bids:latest`
+
 ## Installing binary executables
 
 From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux
@@ -353,18 +366,6 @@ Voilà, you are ready to use dcm2bids or at least
 
 [Go to the How-to section](../../how-to/){ .md-button }
 
-## Containers
-
-We also provide a container image that includes both dcm2niix and dcm2bids which
-you can install using [Docker][docker] or [Apptainer/Singularity][apptainer].
-
-=== "Docker"
-
-    `docker pull unfmontreal/dcm2bids:latest`
-
-=== "Apptainer/Singularity"
-
-    `singularity pull dcm2bids_latest.sif docker://unfmontreal/dcm2bids:latest `
 
 ## Summary of the steps
 

docs/how-to/container.md

@@ -0,0 +1,115 @@
+# dcm2bids with Docker and Apptainer / Singularity
+
+We provide a container image that includes both dcm2niix and dcm2bids as well as pydeface and the BIDS validator. You can find it on [Docker Hub/r/unfmontreal/dcm2bids](https://hub.docker.com/r/unfmontreal/dcm2bids).
+
+You can install it using [Docker](https://www.docker.com/get-started) or [Apptainer/Singularity](https://www.apptainer.org).
+
+## Prerequisites
+
+Before you begin, make sure you have at least one of the following installed:
+
+- Docker: [Download and install Docker](https://www.docker.com/get-started)
+- Apptainer, formerly known as Singularity : [Download and install Apptainer](https://apptainer.org/docs/admin/main/installation.html)
+
+!!! note
+    If you are using a HPC cluster, Apptainer is the recommended choice and is probably installed on your system. Simply load the module (e.g., 
+    `module load apptainer`) and use the `apptainer` command,
+
+## Step 1: Pull the dcm2bids container
+
+To start, you can either pull the dcm2bids image from the Docker Hub repository or [build it from the Dockerfile in the repository](https://github.com/UNFmontreal/Dcm2Bids/blob/dev/Dockerfile).:
+
+=== "Docker"
+
+    ```
+    docker pull unfmontreal/dcm2bids:latest
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    apptainer pull dcm2bids.sif docker://unfmontreal/dcm2bids:latest
+    ```
+
+## Step 2: Test dcm2bids
+
+The default command, or the point of entry, for the container is `dcm2bids`. So every time you run the container, you can pass the `dcm2bids` arguments and options directly. To test the container, run the following command to display the help message for the `dcm2bids` command.
+
+=== "Docker"
+
+    ```
+    docker run --rm -it unfmontreal/dcm2bids:latest --help
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    apptainer run dcm2bids.sif --help
+    ```
+
+## Step 3: Run `dcm2bids_scaffold`
+
+To run `dcm2bids_scaffold`, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). You need to bind the respective volumes.
+
+=== "Docker"
+
+    ```
+    docker run
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    singularity exec \
+    -B /path/to/output-dir:/output \
+    dcm2bids.sif dcm2bids_scaffold -o /output/new_bids_dataset
+    ```
+
+
+## Step 4: Run `dcm2bids_helper`
+
+To run `dcm2bids_helper`, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). To bind the respective volumes, you have two options:
+
+1. Put the input data in the same parent directory as the output directory.
+2. Specify the input data directory as a separate volume.
+
+If you bind the newly scaffolded directory on its own, you can simply use the `-o /output` instead of having to specify the full path to the scaffolded directory. Same goes for the input data directory, if the input data directory is one subject, you can bind it directly to `/input`. If it is the parent directory of multiple subjects, you can bind it to `/input` and specify the specific subject directory (e.g, `-d /input/subject-01`).
+
+=== "Docker"
+
+    ```
+    docker run
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    singularity exec \
+    -B /path/to/input-data:/input \
+    -B /path/to/output-dir/new_bids_dataset:/output \
+    dcm2bids.sif dcm2bids_helper -o /output -d /input
+    ```
+
+## Step 5: Run `dcm2bids`
+
+You can use `run` as in Step 2 or use `exec dcm2bids` to run `dcm2bids` with the appropriate arguments and options. You need to bind the respective volumes.
+
+You can put input data in the same parent directory as the output directory, or you can specify the input data directory as a separate volume. You must also specify the path to the configuration file. If you use the scaffolded dataset, the config file is usually in the `code/` directory.
+
+You can also deface your data and validate your BIDS data using the `--bids_validate` flag.
+
+=== "Docker"
+
+    ```
+    docker run --rm -v
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    singularity run \
+    -B /path/to/input-data:/input \
+    -B /path/to/output-dir/new_bids_dataset:/output \
+    dcm2bids.sif --auto_extract_entities --bids_validate \
+    -o /output -d /input -c /output/code/config.json -p 001
+    ```

docs/how-to/index.md

@@ -16,6 +16,8 @@ title: How-to guides
 
 - [Use advanced commands](./use-advanced-commands.md)
 
+- [Use dcm2bids with Docker or Apptainer/Singularity](./container.md)
+
 ## Development and Community
 
 - [Contribute to dcm2bids](./contributing.md)

mkdocs.yml

@@ -29,10 +29,11 @@ nav:
       - Use main commands: how-to/use-main-commands.md
       - Create a config file: how-to/create-config-file.md
       - Use advanced commands: how-to/use-advanced-commands.md
+      - Use container images: how-to/container.md
+      - Upgrade dcm2bids: upgrade.md
       - Contribute to dcm2bids: how-to/contributing.md
   - Changelog:
     - changelog/index.md
-    - How to upgrade: upgrade.md
   - API Reference: dcm2bids
   - Code of conduct: code_of_conduct.md
 
@@ -76,6 +77,7 @@ theme:
   - content.action.view
   - content.code.annotate
   - content.code.copy
+  # - content.tabs.link
   - content.tooltips
   - navigation.footer
   - navigation.indexes