Merge pull request #2 from SamGuay/update_doc_v3_upgrade

Update doc v3 upgrade

README.md

@@ -27,10 +27,11 @@ Your friendly DICOM converter.
 
 ## Major upgrade with dcm2bids >=3.0.0
 
-Please be careful, dcm2bids>=3.0.0 is not compatible with previous config files. 
-In order to develop dcm2bids new features we had to build from scratch some of its code.
+⚠️ Breaking changes alert ⚠️
 
-Since 3.0.0 and higher, dcm2bids gives more flexible, it is more powerful and reduce the work when creating the config file.
+**dcm2bids>=3.0.0 is not compatible with config files made for v2.1.9 and below**.
+In order to develop dcm2bids new features we had to rewrite some of its code.  
+Since v3.0.0, dcm2bids has become **more powerful** and **more flexible** while reducing the burden of creating config files. Porting you config file should be relatively easy by following the [How-to upgrade][dcm2bids-upgrade] page.
 
 ## Scope
 
@@ -63,12 +64,13 @@ Before posting your question, you may want to first browse through questions tha
 [bids-examples]: https://github.com/bids-standard/bids-examples
 [bids-spec]: https://bids-specification.readthedocs.io/en/stable/
 [dcm2bids-doc]: https://unfmontreal.github.io/Dcm2Bids
-[dcm2bids-install]: https://unfmontreal.github.io/Dcm2Bids/docs/get-started/install/
-[dcm2bids-tutorial]: https://unfmontreal.github.io/Dcm2Bids/docs/tutorial/first-steps/#tutorial-first-steps
-[dcm2bids-advanced]: https://unfmontreal.github.io/Dcm2Bids/docs/advanced/
+[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-upgrade]: https://unfmontreal.github.io/Dcm2Bids/latest/upgrade/
 [dcm2bids-issues]: https://github.com/UNFmontreal/Dcm2Bids/issues
 [dcm2niix-install]: https://github.com/rordenlab/dcm2niix#install
 [dcm2niix-github]: https://github.com/rordenlab/dcm2niix
 [neurostars]: https://neurostars.org/
 [neurostars-dcm2bids]: https://neurostars.org/tag/dcm2bids
-[dcm2bids-contributing]:  https://unfmontreal.github.io/Dcm2Bids/CONTRIBUTING
+[dcm2bids-contributing]:  https://unfmontreal.github.io/Dcm2Bids/latest/how-to/contributing/

dcm2bids/cli/dcm2bids.py

@@ -49,7 +49,7 @@ def _build_arg_parser():
     p.add_argument("--auto_extract_entities",
                    action='store_true',
                    help="If set, it will automatically try to extract entity"
-                   "information [task, dir, echo] based on the suffix and dataType."
+                   "information [task, dir, echo] based on the suffix and datatype."
                    " [%(default)s]")
 
     p.add_argument("--bids_validate",

docs/get-started/index.md

@@ -37,5 +37,5 @@ function:
 [installation]: ./install.md
 [tutorial]: ../tutorial/first-steps.md
 [how-to]: ../how-to
-[reference]: /reference/dcm2bids
+[reference]: ../dcm2bids
 [get-help]: ../how-to/get-help.md

docs/get-started/install.md

@@ -5,14 +5,77 @@ authors:
 date: 2022-04-17
 ---
 
+# Installation
 
-# Installation using binaries
+There are several ways to install dcm2bids.
 
-From dcm2bids>=3.0.0, we provide binaries for mac, windows and ubuntu (debian-based and rhel-based).
+## Installing binary executables
 
-They can easily been downloaded from [the release page](https://github.com/UNFmontreal/Dcm2Bids/releases).
+From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux
+(debian-based and rhel-based).
 
-# Installation using pip or conda
+They can easily been downloaded from
+[the release page](https://github.com/UNFmontreal/Dcm2Bids/releases/latest).
+
+Once downloaded, you should be able to extract the `dcm2bids`,
+`dcm2bids_scaffold`, and `dcm2bids_helper` files and use them with the full
+path.
+
+=== "Example on Ubuntu 22.04"
+
+    ```bash
+    sam:~/software$ curl -fLO https://github.com/unfmontreal/dcm2bids/releases/latest/download/dcm2bids_debian-based_3.0.rc1.tar.gz
+    sam:~/software$ tar -xvf dcm2bids_debian-based*.tar.gz
+    sam:~/software$ cd ../data
+    sam:~/data$ ~/software/dcm2bids_scaffold -o new-bids-project
+    ```
+
+=== "Ouput"
+
+    ```bash
+    sam:~/software$ curl -fLO https://github.com/unfmontreal/dcm2bids/releases/latest/download/dcm2bids_debian-based_3.0.0rc1.tar.gz
+    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                  Dload  Upload   Total   Spent    Left  Speed
+    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
+    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
+    100 40.6M  100 40.6M    0     0  23.2M      0  0:00:01  0:00:01 --:--:-- 36.4M
+
+    sam:~/software$ tar -xvf dcm2bids_debian-based*.tar.gz
+    dcm2bids
+    dcm2bids_helper
+    dcm2bids_scaffold
+
+    sam:~/software$ cd ../data
+
+    sam:~/data$ ~/software/dcm2bids_scaffold -o new-bids-project
+    INFO    | --- dcm2bids_scaffold start ---
+    INFO    | Running the following command: /home/sam/software/dcm2bids_scaffold -o new-bids-project
+    INFO    | OS version: Linux-5.15.0-76-generic-x86_64-with-glibc2.31
+    INFO    | Python version: 3.10.12 | packaged by conda-forge | (main, Jun 23 2023, 22:40:32) [GCC 12.3.0]
+    INFO    | dcm2bids version: 3.0.rc1
+    INFO    | Checking for software update
+    INFO    | Currently using the latest version of dcm2bids.
+    INFO    | The files used to create your BIDS directory were taken from https://github.com/bids-standard/bids-starter-kit.
+
+    INFO    | Tree representation of new-bids-project/
+    INFO    | new-bids-project/
+    INFO    | ├── code/
+    INFO    | ├── derivatives/
+    INFO    | ├── sourcedata/
+    INFO    | ├── tmp_dcm2bids/
+    INFO    | │   └── log/
+    INFO    | │       └── scaffold_20230716-122220.log
+    INFO    | ├── .bidsignore
+    INFO    | ├── CHANGES
+    INFO    | ├── dataset_description
+    INFO    | ├── participants.json
+    INFO    | ├── participants.tsv
+    INFO    | └── README
+    INFO    | Log file saved at new-bids-project/tmp_dcm2bids/log/scaffold_20230716-122220.log
+    INFO    | --- dcm2bids_scaffold end ---
+    ```
+
+## Installing using pip or conda
 
 Before you can use dcm2bids, you will need to get it installed. This page guides
 you through a minimal, typical dcm2bids installation workflow that is sufficient
@@ -143,8 +206,9 @@ installed and correctly setup on your computer as it is the easiest way to
 install dcm2bids and its dependencies on any OS. We assume that if you want to
 install it in a different way, you have enough skills to do it on your own.
 
-If you installed Anaconda and want to use the graphical user interface (GUI), you can follow the steps as
-demonstrated below and only read the steps until the end of the installation guide.
+If you installed Anaconda and want to use the graphical user interface (GUI),
+you can follow the steps as demonstrated below and only read the steps until the
+end of the installation guide.
 
 ??? info "Create your environment with the **Anaconda Navigator** GUI"
 
@@ -177,8 +241,6 @@ But this would install the software in the main environment instead of a
 dedicated one, assuming none were active. This could have atrocious dependencies
 issues in the long-term if you want to install other software.
 
-
-
 #### Create environment.yml
 
 That is exactly why dedicated environments were invented. To help creating

docs/how-to/create-config-file.md

@@ -6,7 +6,7 @@
 {
   "descriptions": [
     {
-      "dataType": "anat",
+      "datatype": "anat",
       "suffix": "T2w",
       "criteria": {
         "SeriesDescription": "*T2*",
@@ -18,7 +18,7 @@
     },
     {
       "id": "task-rest",
-      "dataType": "func",
+      "datatype": "func",
       "suffix": "bold",
       "custom_entities": "task-rest",
       "criteria": {
@@ -27,7 +27,7 @@
       }
     },
     {
-      "dataType": "fmap",
+      "datatype": "fmap",
       "suffix": "fmap",
       "criteria": {
         "ProtocolName": "*field_mapping*"
@@ -38,7 +38,7 @@
     },
     {
       "id": "id_task_learning",
-      "dataType": "func",
+      "datatype": "func",
       "suffix": "bold",
       "custom_entities": "task-learning",
       "criteria": {
@@ -49,7 +49,7 @@
       }
     },
     {
-      "dataType": "fmap",
+      "datatype": "fmap",
       "suffix": "epi",
       "criteria": {
         "SeriesDescription": "fmap_task-learning"
@@ -102,7 +102,7 @@ subject to change depending on the dcm2niix version in use.
 You can enter several criteria. **All criteria must match** for a description to
 be linked to a sidecar.
 
-## dataType
+## datatype
 
 It is a mandatory field. Here is a definition from `bids v1.2.0` :
 
@@ -128,9 +128,9 @@ specifications][bids-spec].
 For a longer example of a Dcm2Bids config json, see
 [here](https://github.com/unfmontreal/Dcm2Bids/blob/master/example/config.json).
 
-Note that the different bids labels must come in a very specific order to be bids valid filenames. 
-If the custom_entities fields that are entered that are in the wrong order,
-then dcm2bids will reorder them for you.
+Note that the different bids labels must come in a very specific order to be
+bids valid filenames. If the custom_entities fields that are entered that are in
+the wrong order, then dcm2bids will reorder them for you.
 
 For example if you entered:
 
@@ -146,15 +146,14 @@ WARNING:dcm2bids.structure:✅ Filename was reordered according to BIDS entity t
                 to:     sub-ID01_task-rest_run-01_bold
 ```
 
-custom_entities could also be combined with extractors. 
-See [custom_entities combined with extractors](./use-advanced-commands.md#custom_entities-combined-with-extractors)
-
+custom_entities could also be combined with extractors. See
+[custom_entities combined with extractors](./use-advanced-commands.md#custom_entities-combined-with-extractors)
 
 ## sidecar_changes, id and IntendedFor
 
-Optional field to change or add information in a sidecar. 
+Optional field to change or add information in a sidecar.
 
-:warning: IntendedFor is now seen as a sidecar_changes.
+:warning: `IntendedFor` is now considered a sidecar_changes.
 
 Example:
 
@@ -166,15 +165,15 @@ Example:
 }
 ```
 
-If you want to add an `IntendedFor` entry or any extra sidecar linked to a specific file, 
-you will need to set an id to the corresponding description and put the same id with `IntendedFor`.
-
-Fo example, **`task_rest`** means it is intended for `task-rest_bold` 
-and **`id_task_learning`** is intended for `task-learning_bold`. 
+If you want to add an `IntendedFor` entry or any extra sidecar linked to a
+specific file, you will need to set an id to the corresponding description and
+put the same id with `IntendedFor`.
 
-You could also use this feature to feed sidecar such as `Source`` for example 
-or anything that suits your needs.
+Fo example, **`task_rest`** means it is intended for `task-rest_bold` and
+**`id_task_learning`** is intended for `task-learning_bold`.
 
+You could also use this feature to feed sidecar such as `Source`` for example or
+anything that suits your needs.
 
 ## Multiple config files
 

docs/how-to/index.md

@@ -18,4 +18,4 @@ title: How-to guides
 
 ## Development and Community
 
-- [Contribute to dcm2bids](/CONTRIBUTING.md)
+- [Contribute to dcm2bids](./contributing.md)