Merge pull request #88 from effigies/doc/round-2

doc: Round 2

Author: effigies

.github/CONTRIBUTING.md

@@ -94,61 +94,13 @@ consider:
      `upstream` refers to the original BIDS validator repository on GitHub
    - you can use `upstream` to always stay up to date with changes that are
      being made on the original BIDS validator. For that, simply navigate to
-     the `master` branch of **your** repository using `git checkout master`,
-     and then run `git pull upstream master`
+     the `main` branch of **your** repository using `git checkout main`,
+     and then run `git pull upstream main`
 1. When you get completely stuck with your repository and you just want to
    reset it to be an exact mirror of the original BIDS validator, you can
    run the following command (Note: this will discard all current changes):
-   - first checkout your master: `git checkout master`
-   - then run: `git reset --hard upstream/master`
-
-## Extending the BIDS validator for a BIDS Extension Proposal (BEP)
-
-### Regular expressions
-
-A lot of validation of BIDS files and directories is happening through
-[regular expressions](https://en.wikipedia.org/wiki/Regular_expression).
-You can see the regular expressions
-[here](https://github.com/bids-standard/bids-validator/tree/master/bids-validator/bids_validator/rules).
-
-Changing the regular expressions can be a delicate thing, so we recommend
-testing your regular expressions exhaustively. A helpful website for that can
-be [https://regex101.com/](https://regex101.com/), where you can test regular
-expressions in your browser, and even save and share them.
-
-### JSON schemas
-
-Another big chunk of BIDS validation is happening through [JSON schemas](https://json-schema.org/).
-In BIDS, a lot of metadata is saved in JSON files, which are very well defined
-and readable by a computer. With these properties, we can make requirements of
-how a JSON ought to look like. You can find our JSON schemas
-[here](https://github.com/bids-standard/bids-validator/tree/master/bids-validator/validators/json/schemas).
-
-As with regular expressions, we recommend lots of testing on the JSON schemas.
-You can easily have a first try of that using a website like
-[https://www.jsonschemavalidator.net/](https://www.jsonschemavalidator.net/).
-Simply copy over a schema from BIDS validator to the left field, and try to
-comply to the schema, or trigger an error by typing in a JSON to the right
-field.
-
-### Writing tests
-
-For every change you make it is important to include a test. That way, we can
-make sure that the behavior of BIDS validator is as expected, and furthermore
-we will be notified whenever a contributor makes a change in the code that
-breaks the expected behavior of the BIDS validator.
-
-A test usually provides some known data, and let's the software run over it ...
-just to check whether the output is as we know it should be (because we know
-the data, after all).
-
-You can get a good impression using the following links:
-
-- [How regular expressions are tested](https://github.com/bids-standard/bids-validator/blob/master/bids-validator/tests/type.spec.js)
-- [How JSON schemas are tested](https://github.com/bids-standard/bids-validator/blob/master/bids-validator/tests/json.spec.js)
-- [How TSV files are tested](https://github.com/bids-standard/bids-validator/blob/master/bids-validator/tests/tsv.spec.js)
-
-For more information on how to run the tests check the [testing section](./README.md#testing) of the README.
+   - first checkout your main: `git checkout main`
+   - then run: `git reset --hard upstream/main`
 
 [link_git]: https://git-scm.com/
 [link_handbook]: https://guides.github.com/introduction/git-handbook/

docs/_static/chromium_permissions_dark.png

@@ -36,7 +36,13 @@
         "text": "The BIDS Validator",
         "image_light": "_static/BIDS_logo_black.svg",
         "image_dark": "_static/BIDS_logo_white.svg",
-    }
+    },
+    "repository_url": "https://github.com/bids-standard/bids-validator",
+    "path_to_docs": "docs",
+    "use_source_button": True,
+    "use_edit_page_button": True,
+    "use_repository_button": True,
+    "use_issues_button": True,
 }
 
 # -- Customization

docs/_static/chromium_permissions_light.png

@@ -64,7 +64,7 @@ bids-validator <dataset>
 | `--ignoreNiftiHeaders`         | Do not open NIfTI files, skipping any checks that rely on NIfTI header data                                                                                           |
 | `--filenameMode`               | Perform filename checks only on newline-separated filenames read from [stdin]                                                                                         |
 | `--blacklistModalities MOD...` | Raise error if passed modalities are detected in the dataset. Modalities may be any of `mri`, `eeg`, `ieeg`, `meg`, `beh`, `pet`, `micr`, `motion`, `nirs`, or `mrs`. |
-| `--debug LEVEL`                | Enable logging at the specified level. Default level is `ERROR`. Levels include (from most to least verbose): `NOTSET`, `DEBUG`, `INFO`, WARN`, `ERROR`, `CRITICAL`.  |
+| `--debug LEVEL`                | Enable logging at the specified level. Default level is `ERROR`. Levels include (from most to least verbose): `NOTSET`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRITICAL`. |
 | `--color`, `--no-color`        | Enable/disable color. The validator also respects the [NO_COLOR] and [FORCE_COLOR] environment variables.                                                             |
 
 ## Configuration file

docs/_static/firefox_permissions_dark.png

@@ -1 +1,50 @@
 # Using the web validator
+
+The web validator is the primary interface to the validator,
+hosted at <https://bids-standard.github.io/bids-validator/>
+
+![The web interface to the BIDS Validator with the "Select Dataset Files" button highlighted.
+(Dark theme)](../_static/web_entrypoint_dark.png){.only-dark .no-scaled-link width="50%" align=center}
+![The web interface to the BIDS Validator with the "Select Dataset Files" button highlighted.
+(Light theme)](../_static/web_entrypoint_light.png){.only-light .no-scaled-link width="50%" align=center}
+
+To validate a dataset, click the "Select Dataset Files" and select a directory to validate.
+The directory must contain a `dataset_description.json` to be identified as a BIDS dataset.
+
+When you select a directory, you will get a permission prompt,
+verifying that you want to provide access to the directory.
+
+::::{tab-set}
+
+:::{tab-item} Firefox permission prompt
+
+![The Firefox permissions prompt (Dark theme)](../_static/firefox_permissions_dark.png){.only-dark width="50%" align=center}
+![The Firefox permissions prompt (Light theme)](../_static/firefox_permissions_light.png){.only-light width="50%" align=center}
+
+:::
+:::{tab-item} Chrome permission prompt
+:sync: install
+
+![The Chromium permissions notice (Dark theme)](../_static/chromium_permissions_dark.png){.only-dark width="50%" align=center}
+![The Chromium permissions notice (Light theme)](../_static/chromium_permissions_light.png){.only-light width="50%" align=center}
+
+:::
+::::
+
+At present (November 2024), Firefox browsers present the request to "Upload" data,
+while Chromium-based browsers (Google Chrome, Microsoft Edge, and others) request permission
+to "view files".
+In both cases, confirming allows the Javascript application to read the files and perform validation,
+but those files are never sent to a remote server.
+
+## The Legacy Validator
+
+The current BIDS Validator is a complete rewrite of the original BIDS Validator,
+based on the [BIDS Schema].
+The original validator, now called the "legacy validator", can be found at
+<https://bids-standard.github.io/legacy-validator/>.
+
+It is not recommended to use this validator, as it will become increasingly out-of-date,
+but it may be useful for comparative purposes.
+
+[BIDS Schema]: https://bidsschematools.readthedocs.io