Merge pull request #87 from effigies/feat/docs

doc: Initialize Sphinx docs

Author: effigies

.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

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.

docs/.gitignore

@@ -0,0 +1 @@
+_build/

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)