Skip to content

Commit 0524a4c

Browse files
arnaudborearnaudbore
authored
Merge pull request UNFmontreal#267 from SamGuay/enh_auto_help_doc
[ENH] - Automate help message in doc
2 parents b561bdb + 490f47f commit 0524a4c

File tree

5 files changed

+18
-169
lines changed

5 files changed

+18
-169
lines changed

‎.github/workflows/publish_doc.yaml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,9 @@ jobs:
4747
run: |
4848
python3 -m pip install -r ./requirements-doc.txt
4949
pip install -e .
50+
dcm2bids -h > docs_helper/help.txt
51+
dcm2bids_helper -h > docs_helper/helper.txt
52+
dcm2bids_scaffold -h > docs_helper/help_scaffold.txt
5053
5154
- name: Set git credentials
5255
run: |

‎.gitignore

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,4 +135,7 @@ tests/data/*
135135
!tests/data/sidecars/*
136136

137137
# dcm2bids documentation
138-
/site
138+
/site
139+
docs_helper/help.txt
140+
docs_helper/help_scaffold.txt
141+
docs_helper/helper.txt

‎docs/get-started/install.md

Lines changed: 1 addition & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -343,36 +343,7 @@ dcm2bids command such as `dcm2bids --help`:
343343

344344
```bash hl_lines="1"
345345
(dcm2bids) sam:~/dcm2bids-proj$ dcm2bids --help
346-
usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c
347-
CONFIG [-o OUTPUT_DIR] [--force_dcm2bids] [--skip_dcm2niix]
348-
[--clobber] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a]
349-
350-
Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure
351-
dcm2bids 2.1.7
352-
353-
options:
354-
-h, --help show this help message and exit
355-
-d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
356-
DICOM directory(ies)
357-
-p PARTICIPANT, --participant PARTICIPANT
358-
Participant ID
359-
-s SESSION, --session SESSION
360-
Session ID
361-
-c CONFIG, --config CONFIG
362-
JSON configuration file (see example/config.json)
363-
-o OUTPUT_DIR, --output_dir OUTPUT_DIR
364-
Output BIDS directory, Default: current directory
365-
(/home/sam/dcm2bids-proj)
366-
--force_dcm2bids Overwrite previous temporary dcm2bids output if it exists
367-
--skip_dcm2niix Skip dcm2niix conversion. Option -d should contains NIFTI and json files.
368-
--clobber Overwrite output if it exists
369-
-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
370-
Set logging level
371-
-a, --anonymizer This option no longer exists from the script in this
372-
release. See:https://github.com/unfmontreal/Dcm2Bids/blob/m
373-
aster/README.md#defaceTpl
374-
375-
Documentation at https://github.com/unfmontreal/Dcm2Bids
346+
--8<-- "docs_helper/help.txt"
376347
```
377348

378349
Voilà, you are ready to use dcm2bids or at least

‎docs/how-to/use-advanced-commands.md

Lines changed: 2 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -221,39 +221,8 @@ command.
221221

222222
=== "Output"
223223

224-
```sh hl_lines="2-3"
225-
(dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ dcm2bids --help
226-
usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c CONFIG [-o OUTPUT_DIR]
227-
[--auto_extract_entities] [--bids_validate] [--force_dcm2bids] [--skip_dcm2niix] [--clobber]
228-
[-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a]
229-
230-
Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure
231-
dcm2bids 3.0.0
232-
233-
options:
234-
-h, --help show this help message and exit
235-
-d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
236-
DICOM directory(ies)
237-
-p PARTICIPANT, --participant PARTICIPANT
238-
Participant ID
239-
-s SESSION, --session SESSION
240-
Session ID
241-
-c CONFIG, --config CONFIG
242-
JSON configuration file (see example/config.json)
243-
-o OUTPUT_DIR, --output_dir OUTPUT_DIR
244-
Output BIDS directory, Default: current directory (/home/sam/dcm2bids-tutorial/bids_project)
245-
--auto_extract_entities If set, it will automatically try to extract entity information [task, dir, echo]
246-
depending on the suffix and datatype. [False]
247-
--bids_validate If set, once your conversion is done it will check if your output folder is BIDS valid. [False]
248-
bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart
249-
--force_dcm2bids Overwrite previous temporary dcm2bids output if it exists.
250-
--skip_dcm2niix Skip dcm2niix conversion. Option -d should contains NIFTI and json files.
251-
--clobber Overwrite output if it exists.
252-
-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
253-
Set logging level
254-
255-
Documentation at https://github.com/unfmontreal/Dcm2Bids
256-
224+
```sh
225+
--8<-- "docs_helper/help.txt"
257226
```
258227

259228
### `--auto_extract_entities`

‎docs/tutorial/first-steps.md

Lines changed: 8 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -79,42 +79,7 @@ You can test it with any command but a safe way is to use the `--help` command.
7979

8080
```sh
8181
(dcm2bids) sam:~$ dcm2bids --help
82-
usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c
83-
CONFIG [-o OUTPUT_DIR][--auto_extract_entities] [--bids_validate]
84-
[--force_dcm2bids] [--skip_dcm2niix] [--clobber]
85-
[-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a]
86-
87-
Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure
88-
dcm2bids 2.1.7
89-
90-
options:
91-
-h, --help show this help message and exit
92-
-d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
93-
DICOM directory(ies)
94-
-p PARTICIPANT, --participant PARTICIPANT
95-
Participant ID
96-
-s SESSION, --session SESSION
97-
Session ID
98-
-c CONFIG, --config CONFIG
99-
JSON configuration file (see example/config.json)
100-
-o OUTPUT_DIR, --output_dir OUTPUT_DIR
101-
Output BIDS directory, Default: current directory
102-
(/home/sam)
103-
--auto_extract_entities
104-
If set, it will automatically try to extract entityinformation [task, dir, echo] based on the suffix and datatype. [False]
105-
--bids_validate If set, once your conversion is done it will check if your output folder is BIDS valid. [False]
106-
bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart
107-
--force_dcm2bids Overwrite previous temporary dcm2bids output if it exists.
108-
--skip_dcm2niix Skip dcm2niix conversion. Option -d should contains NIFTI and json files.
109-
--clobber Overwrite output if it exists.
110-
-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
111-
Set logging level
112-
-a, --anonymizer This option no longer exists from the script in this
113-
release. See:https://github.com/unfmontreal/Dcm2Bids/blob/m
114-
aster/README.md#defaceTpl
115-
116-
Documentation at https://github.com/unfmontreal/Dcm2Bids
117-
82+
--8<-- "docs_helper/help.txt"
11883
```
11984

12085
??? bug "What you can do if you did not get this output"
@@ -189,25 +154,12 @@ option.
189154

190155
=== "Output"
191156

192-
```sh hl_lines="9-10"
157+
```sh hl_lines="11-12"
193158
(dcm2bids) sam:~/dcm2bids-tutorial$ dcm2bids_scaffold --help
194-
usage: dcm2bids_scaffold [-h] [-o OUTPUT_DIR]
195-
196-
Create basic BIDS files and directories
197-
198-
Based on the material provided by
199-
https://github.com/bids-standard/bids-starter-kit
200-
201-
options:
202-
-h, --help show this help message and exit
203-
-o OUTPUT_DIR, --output_dir OUTPUT_DIR
204-
Output BIDS directory, Default: current directory
205-
206-
Documentation at https://github.com/unfmontreal/Dcm2Bids
207-
159+
--8<-- "docs_helper/help_scaffold.txt"
208160
```
209161

210-
As you can see at lines 9-10, `dcm2bids_scaffold` has an `--output_dir` (or `-o`
162+
As you can see at lines 11-12, `dcm2bids_scaffold` has an `--output_dir` (or `-o`
211163
for short) option with a default option, which means you can either specify
212164
where you want the scaffolding to happen to be or it will create the scaffold in
213165
the current directory as a default.
@@ -487,27 +439,9 @@ As usual the first command will be to request the help info.
487439

488440
=== "Output"
489441

490-
```sh hl_lines="6 8"
442+
```sh hl_lines="11 13 15"
491443
(dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ dcm2bids_helper --help
492-
usage: dcm2bids_helper [-h] -d DICOM_DIR [DICOM_DIR ...] [-o OUTPUT_DIR]
493-
494-
options:
495-
-h, --help show this help message and exit
496-
-d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
497-
DICOM files directory
498-
-o OUTPUT_DIR, --output_dir OUTPUT_DIR
499-
Output BIDS directory, Default: current directory
500-
-n [NEST], --nest [NEST]
501-
Nest a directory in <output_dir>. Useful if many helper runs are needed
502-
to make a config file due to slight variations in MRI acquisitions.
503-
Defaults to DICOM_DIR if no name is provided.
504-
(Default: [False])
505-
--force, --force_dcm2bids
506-
Force command to overwrite existing output files.
507-
-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
508-
Set logging level to the console. [INFO]
509-
510-
Documentation at https://github.com/unfmontreal/Dcm2Bids
444+
--8<-- "docs_helper/helper.txt"
511445
```
512446

513447
To run the commands, you have to specify the `-d` option, namely the input
@@ -1068,39 +1002,8 @@ command.
10681002
=== "Output"
10691003

10701004
```sh hl_lines="2-3"
1071-
(dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ dcm2bids --help
1072-
usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c CONFIG [-o OUTPUT_DIR]
1073-
[--auto_extract_entities] [--bids_validate] [--force_dcm2bids] [--skip_dcm2niix] [--clobber]
1074-
[-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a]
1075-
1076-
Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure
1077-
dcm2bids 2.1.7
1078-
1079-
options:
1080-
-h, --help show this help message and exit
1081-
-d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
1082-
DICOM directory(ies)
1083-
-p PARTICIPANT, --participant PARTICIPANT
1084-
Participant ID
1085-
-s SESSION, --session SESSION
1086-
Session ID
1087-
-c CONFIG, --config CONFIG
1088-
JSON configuration file (see example/config.json)
1089-
-o OUTPUT_DIR, --output_dir OUTPUT_DIR
1090-
Output BIDS directory, Default: current directory (/home/sam/dcm2bids-tutorial/bids_project)
1091-
--auto_extract_entities
1092-
If set, it will automatically try to extract entityinformation [task, dir, echo] based on the suffix and datatype. [False]
1093-
--bids_validate If set, once your conversion is done it will check if your output folder is BIDS valid. [False]
1094-
bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart
1095-
--force_dcm2bids Overwrite previous temporary dcm2bids output if it exists.
1096-
--skip_dcm2niix Skip dcm2niix conversion. Option -d should contains NIFTI and json files.
1097-
--clobber Overwrite output if it exists.
1098-
-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
1099-
Set logging level
1100-
-a, --anonymizer This option no longer exists from the script in this release. See:https://github.com/unfmontreal/Dcm2Bids/blob/master/README.md#defaceTpl
1101-
1102-
Documentation at https://github.com/unfmontreal/Dcm2Bids
1103-
1005+
(dcm2bids) sam:~$ dcm2bids --help
1006+
--8<-- "docs_helper/help.txt"
11041007
```
11051008

11061009
As you can see, to run the `dcm2bids` command, you have to specify at least 3

0 commit comments

Comments
 (0)