diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..07909054 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: ubuntu-lts-latest + tools: + python: latest + +python: + install: + requirements: docs/requirements.txt + +sphinx: + configuration: docs/conf.py diff --git a/README.md b/README.md index 8a786bd6..f2c18e2b 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,33 @@ -# Deno based bids-validator +# The BIDS Validator -## Intro +The BIDS Validator is a web application, command-line utility, +and Javascript/Typescript library for assessing compliance with the +[Brain Imaging Data Structure][BIDS] standard. -This is a full rewrite of the bids-validator JavaScript implementation designed to use the [bids-specification schema](https://github.com/bids-standard/bids-specification/tree/master/src/schema) to apply the majority of validation rules. +## Getting Started -Deno is a JavaScript and TypeScript runtime that is used to run the schema based validator. Deno is simpler than Node.js and only requires one tool to use, the Deno executable itself. To install Deno, follow these [install instructions for your platform](https://deno.land/manual/getting_started/installation). +In most cases, +the simplest way to use the validator is to browse to the [BIDS Validator][] web page: -## Usage +![The web interface to the BIDS Validator with the "Select Dataset Files" button highlighted. +(Dark theme)](_static/web_entrypoint_dark.png){.only-dark 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 width="50%" align=center} -To use the latest validator hosted at https://deno.land/x/bids_validator, use the following command: +The web validator runs in-browser, and does not transfer data to any remote server. -```console -$ deno run --allow-read --allow-env https://deno.land/x/bids_validator/bids-validator.ts path/to/dataset +In some contexts, such as when working on a remote server, +it may be easier to use the command-line. +The BIDS Validator can be run with the [Deno] runtime +(see [Deno - Installation][] for detailed installation instructions): + +```shell +deno run -ERN jsr:@bids/validator ``` -Deno by default sandboxes applications like a web browser. `--allow-read` allows the validator to read local files, and `--allow-env` enables OS-specific features. +Deno by default sandboxes applications like a web browser. +`-E`, `-R` and `-N` allow the validator to read environment variables, +local files, and network locations. ### Configuration file @@ -38,13 +51,13 @@ Pass the `--json` flag to see the issues in detail. ### Development tools -From the repository root, use `bids-validator/bids-validator-deno` to run with all permissions enabled by default: +From the repository root, use `./local-run` to run with all permissions enabled by default: ```shell # Run from within the /bids-validator directory cd bids-validator # Run validator: -./bids-validator-deno path/to/dataset +./local-run path/to/dataset ``` ## Schema validator test suite @@ -56,12 +69,6 @@ deno test --allow-env --allow-read --allow-write src/ This test suite includes running expected output from bids-examples and may throw some expected failures for bids-examples datasets where either the schema or validator are misaligned with the example dataset while under development. -## Refreshing latest specification - -If you are validating with the latest specification instead of a specific version, the validator will hold onto a cached version. You can request the newest version by adding the `--reload` argument to obtain the newest specification definition. - -`deno run --reload=https://bids-specification.readthedocs.io/en/latest/schema.json src/main.ts` - ## Modifying and building a new schema To modify the schema a clone of bids-standard/bids-specification will need to be made. README and schema itself live here https://github.com/bids-standard/bids-specification/tree/master/src/schema. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..69fa449d --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/BIDS_logo_black.svg b/docs/_static/BIDS_logo_black.svg new file mode 100644 index 00000000..9f1718f7 --- /dev/null +++ b/docs/_static/BIDS_logo_black.svg @@ -0,0 +1 @@ +Ресурс 2 diff --git a/docs/_static/BIDS_logo_white.svg b/docs/_static/BIDS_logo_white.svg new file mode 100644 index 00000000..629a5392 --- /dev/null +++ b/docs/_static/BIDS_logo_white.svg @@ -0,0 +1 @@ +Ресурс 1 diff --git a/docs/_static/web_entrypoint_dark.png b/docs/_static/web_entrypoint_dark.png new file mode 100644 index 00000000..a6df0e7c Binary files /dev/null and b/docs/_static/web_entrypoint_dark.png differ diff --git a/docs/_static/web_entrypoint_light.png b/docs/_static/web_entrypoint_light.png new file mode 100644 index 00000000..ab1b8dba Binary files /dev/null and b/docs/_static/web_entrypoint_light.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..710b11c1 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,50 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'BIDS Validator' +copyright = '2024, BIDS Contributors' +author = 'BIDS Contributors' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + # 'sphinx_js', + 'myst_parser', + 'sphinx_copybutton', + 'sphinx_design', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_book_theme' +html_static_path = ['_static'] + +html_theme_options = { + "logo": { + "text": "The BIDS Validator", + "image_light": "_static/BIDS_logo_black.svg", + "image_dark": "_static/BIDS_logo_white.svg", + } +} + +# -- Customization +# js_language = 'typescript' +# js_source_path = '../src/**/*.ts' +# primary_domain = 'js' + +myst_enable_extensions = [ + "attrs_inline", + "colon_fence", +] diff --git a/docs/dev/contributing.md b/docs/dev/contributing.md new file mode 120000 index 00000000..95181235 --- /dev/null +++ b/docs/dev/contributing.md @@ -0,0 +1 @@ +../../.github/CONTRIBUTING.md \ No newline at end of file diff --git a/docs/dev/environment.md b/docs/dev/environment.md new file mode 100644 index 00000000..dc310f22 --- /dev/null +++ b/docs/dev/environment.md @@ -0,0 +1 @@ +# Development environment diff --git a/docs/dev/using-the-api.md b/docs/dev/using-the-api.md new file mode 100644 index 00000000..3017721d --- /dev/null +++ b/docs/dev/using-the-api.md @@ -0,0 +1 @@ +# Using the API diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..6055c5d5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,56 @@ +# The BIDS Validator + +The BIDS Validator is a web application, command-line utility, +and Javascript/Typescript library for assessing compliance with the +[Brain Imaging Data Structure][BIDS] standard. + +## Getting Started + +In most cases, +the simplest way to use the validator is to browse to the [BIDS Validator][] web page: + +![The web interface to the BIDS Validator with the "Select Dataset Files" button highlighted. +(Dark theme)](_static/web_entrypoint_dark.png){.only-dark 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 width="50%" align=center} + +The web validator runs in-browser, and does not transfer data to any remote server. + +In some contexts, such as when working on a remote server, +it may be easier to use the command-line. +The BIDS Validator can be run with the [Deno] runtime +(see [Deno - Installation][] for detailed installation instructions): + +```shell +deno run -A jsr:@bids/validator +``` + +```{toctree} +:hidden: +:caption: User guide + +user_guide/web.md +user_guide/command-line.md +user_guide/issues.md +``` + +```{toctree} +:hidden: +:caption: Developer guide + +dev/using-the-api.md +dev/contributing.md +dev/environment.md +``` + +```{toctree} +:hidden: +:caption: Reference + +API Reference +``` + +[BIDS]: https://bids.neuroimaging.io +[BIDS Validator]: https://bids-standard.github.io/bids-validator/ +[Deno]: https://deno.com/ +[Deno - Installation]: https://docs.deno.com/runtime/getting_started/installation/ diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..d906c34c --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinx +myst_parser +sphinx-book-theme +sphinx-copybutton +sphinx-design diff --git a/docs/user_guide/command-line.md b/docs/user_guide/command-line.md new file mode 100644 index 00000000..f57eb049 --- /dev/null +++ b/docs/user_guide/command-line.md @@ -0,0 +1,97 @@ +# Using the command line + +The BIDS Validator may be run with the [Deno] runtime. +For detailed installation instructions, see [Deno - Installation][]. +Deno is also available as a [conda-forge package](https://anaconda.org/conda-forge/deno). + +## Installation + +In general, there is no need to install Deno applications. +`deno run` allows running from the Javascript Repository: + +```sh +deno run -ERN jsr:@bids/validator +``` + +However, you can also install a lightweight script (into `$HOME/.deno/bin`): + +```sh +deno install -ERN -g -n bids-validator jsr:@bids/validator +``` + +Or compile a bundled binary: + +```sh +deno compile -ERN -o bids-validator jsr:@bids/validator +``` + +## Usage + +The BIDS Validator takes a single dataset as input: + +::::{tab-set} +:sync-group: run-method + +:::{tab-item} Deno run +:sync: run + +```sh +deno run -ERN jsr:@bids/validator +``` + +::: +:::{tab-item} Installed +:sync: install + +```sh +bids-validator +``` + +::: +:::: + +### Options + +| Option | Description | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-v`, `--verbose` | Log more extensive information about issues | +| `-s URL`, `--schema URL` | Specify an alternative [BIDS Schema] for validation | +| `-c FILE`, `--config FILE` | Provide a [configuration file](#configuration-file) | +| `-r`, `--recursive` | Validate datasets found in `derivatives/` subdirectories, recursively | +| `-o FILE`, `--outfile FILE` | Write validation results to file. | +| `--json` | Output results in machine-readable [JSON] | +| `--ignoreWarnings` | Do not report warnings | +| `--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`. | +| `--color`, `--no-color` | Enable/disable color. The validator also respects the [NO_COLOR] and [FORCE_COLOR] environment variables. | + +## Configuration file + +The schema validator accepts a JSON configuration file that reclassifies issues as +warnings, errors or ignored. + +```json +{ + "ignore": [ + { "code": "JSON_KEY_RECOMMENDED", "location": "/T1w.json" } + ], + "warning": [], + "error": [ + { "code": "NO_AUTHORS" } + ] +} +``` + +The issues are partial matches of the [Issues] that the validator accumulates. +Pass the `--json` flag to see the issues in detail. + +[Deno]: https://deno.com/ +[Deno - Installation]: https://docs.deno.com/runtime/getting_started/installation/ +[JSON]: https://www.json.org/json-en.html +[BIDS Schema]: https://bidsschematools.readthedocs.io +[stdin]: https://en.wikipedia.org/wiki/Standard_streams +[NO_COLOR]: https://no-color.org +[FORCE_COLOR]: https://force-color.org +[Issues]: https://jsr.io/@bids/validator/doc/issues/~/Issue diff --git a/docs/user_guide/issues.md b/docs/user_guide/issues.md new file mode 100644 index 00000000..31189e1f --- /dev/null +++ b/docs/user_guide/issues.md @@ -0,0 +1 @@ +# Understanding issues diff --git a/docs/user_guide/web.md b/docs/user_guide/web.md new file mode 100644 index 00000000..617f51e6 --- /dev/null +++ b/docs/user_guide/web.md @@ -0,0 +1 @@ +# Using the web validator