Skip to content

Commit

Permalink
[DOC] Preface each macro call with comment (#1052)
Browse files Browse the repository at this point in the history 
* [DATALAD RUNCMD] add filetree macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_filetree_example/i \\<!-- This block generates a file tree.\\nA guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* [DATALAD RUNCMD] add filetree macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_filetree_example/i \\<!-- This block generates a file tree.\\nA guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* [DATALAD RUNCMD] add metadata table macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_metadata_table/i \\<!-- This block generates a metadata table.\\nThe definitions of these fields can be found in\\n  src/schema/objects/metadata.yaml\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* [DATALAD RUNCMD] add metadata table macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_metadata_table/i \\<!-- This block generates a metadata table.\\nThe definitions of these fields can be found in\\n  src/schema/objects/metadata.yaml\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* [DATALAD RUNCMD] add columns table macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_columns_table/i \\<!-- This block generates a columns table.\\nThe definitions of these fields can be found in\\n  src/schema/objects/columns.yaml\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* [DATALAD RUNCMD] add columns table macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_columns_table/i \\<!-- This block generates a columns table.\\nThe definitions of these fields can be found in\\n  src/schema/objects/columns.yaml\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* [DATALAD RUNCMD] add suffix macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_suffix_table/i \\<!--\\nThis block generates a suffix table.\\nThe definitions of these fields can be found in\\n  src/schema/rules/datatypes\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* [DATALAD RUNCMD] add filename template macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_filename_template/i \\<!--\\nThis block generates a filename templates.\\nThe inputs for this macro can be found in the folder\\n  src/schema/rules/datatypes\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* update other macros with comments

* indent comment
  • Loading branch information
@Remi-Gau
Remi-Gau authored Apr 6, 2022
1 parent ee9e8b5 commit 252e2c4
Show file tree
Hide file tree
Showing 21 changed files with 1,115 additions and 0 deletions.
34 changes: 34 additions & 0 deletions src/02-common-principles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,10 @@ However, in the case that these data are to be included:

Alternatively one can organize their data in the following way

<!-- This block generates a file tree.
A guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filetree_example(
{
"my_dataset-1": {
Expand Down Expand Up @@ -360,6 +364,10 @@ Derivatives can be stored/distributed in two ways:

Example of a derivative dataset including the raw dataset as source:

<!-- This block generates a file tree.
A guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filetree_example(
{
"my_processed_data": {
Expand Down Expand Up @@ -461,6 +469,12 @@ Note that if a field name included in the data dictionary matches a column name
then that field MUST contain a description of the corresponding column,
using an object containing the following fields:

<!-- This block generates a metadata table.
The definitions of these fields can be found in
src/schema/objects/metadata.yaml
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_metadata_table(
{
"LongName": "OPTIONAL",
Expand Down Expand Up @@ -592,6 +606,10 @@ Corollaries:

Example 1: Demonstration of inheritance principle

<!-- This block generates a file tree.
A guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filetree_example(
{
"sub-01": {
Expand Down Expand Up @@ -635,6 +653,10 @@ absence in the metadata file at the lower level (rule 5.b; corollary 3).

Example 2: Impermissible use of multiple metadata files at one directory level (rule 4)

<!-- This block generates a file tree.
A guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filetree_example(
{
"sub-01": {
Expand All @@ -656,6 +678,10 @@ Example 2: Impermissible use of multiple metadata files at one directory level (
Example 3: Modification of filesystem structure from Example 2 to satisfy inheritance
principle requirements

<!-- This block generates a file tree.
A guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filetree_example(
{
"sub-01": {
Expand All @@ -676,6 +702,10 @@ principle requirements

Example 4: Single metadata file applying to multiple data files (corollary 2)

<!-- This block generates a file tree.
A guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filetree_example(
{
"sub-01": {
Expand Down Expand Up @@ -823,6 +853,10 @@ This is an example of the directory and file structure. Because there is only on
session, the session level is not required by the format. For details on
individual files see descriptions in the next section:

<!-- This block generates a file tree.
A guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filetree_example(
{
"sub-control01": {
Expand Down
42 changes: 42 additions & 0 deletions src/03-modality-agnostic-files.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@ Templates:
The file `dataset_description.json` is a JSON file describing the dataset.
Every dataset MUST include this file with the following fields:

<!-- This block generates a metadata table.
The definitions of these fields can be found in
src/schema/objects/metadata.yaml
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_metadata_table(
{
"Name": "REQUIRED",
Expand Down Expand Up @@ -99,6 +105,12 @@ top level of every derived dataset:
In contrast to raw BIDS datasets, derived BIDS datasets MUST include a
`GeneratedBy` key:

<!-- This block generates a metadata table.
The definitions of these fields can be found in
src/schema/objects/metadata.yaml
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_metadata_table(
{
"GeneratedBy": "REQUIRED"
Expand Down Expand Up @@ -209,6 +221,12 @@ Commonly used *optional* columns in `participants.tsv` files are `age`, `sex`,
of these columns, and in case that you do use them, we RECOMMEND to use the
following values for them:

<!-- This block generates a columns table.
The definitions of these fields can be found in
src/schema/objects/columns.yaml
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_columns_table(
{
"participant_id": ("REQUIRED", "There MUST be exactly one row for each participant."),
Expand Down Expand Up @@ -288,6 +306,12 @@ The purpose of this file is to describe properties of samples, indicated by the
This file is REQUIRED if `sample-<label>` is present in any filename within the dataset.
Each sample MUST be described by one and only one row.

<!-- This block generates a columns table.
The definitions of these fields can be found in
src/schema/objects/columns.yaml
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_columns_table(
{
"sample_id": ("REQUIRED", "The combination of `sample_id` and `participant_id` MUST be unique."),
Expand Down Expand Up @@ -358,6 +382,12 @@ MAY be accompanied by a JSON file describing the columns in detail

In addition to the column descriptions, the JSON file MAY contain the following fields:

<!-- This block generates a metadata table.
The definitions of these fields can be found in
src/schema/objects/metadata.yaml
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_metadata_table(
{
"MeasurementToolMetadata": "OPTIONAL",
Expand Down Expand Up @@ -424,6 +454,12 @@ Some recordings consist of multiple parts, that span several files,
for example through `echo-`, `part-`, or `split-` entities.
Such recordings MUST be documented with one row per file.

<!-- This block generates a columns table.
The definitions of these fields can be found in
src/schema/objects/columns.yaml
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_columns_table(
{
"filename": ("REQUIRED", "There MUST be exactly one row for each file."),
Expand Down Expand Up @@ -467,6 +503,12 @@ These files MUST include a `session_id` column and describe each session by one
Column names in `sessions.tsv` files MUST be different from group level participant key column names in the
[`participants.tsv` file](./03-modality-agnostic-files.md#participants-file).

<!-- This block generates a columns table.
The definitions of these fields can be found in
src/schema/objects/columns.yaml
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_columns_table(
{
"session_id": ("REQUIRED", "There MUST be exactly one row for each session."),
Expand Down
Loading

0 comments on commit 252e2c4

Please sign in to comment.