doc: Add quickstart to schema docs

Author: effigies

tools/schemacode/docs/index.rst

@@ -5,6 +5,12 @@ Contents
 ========
 
 .. toctree::
+   :caption: Tutorial
+
+   quickstart
+
+.. toctree::
+   :caption: Reference
    :maxdepth: 2
 
    description

tools/schemacode/docs/quickstart.md

@@ -0,0 +1,191 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.17.2
+kernelspec:
+  name: python3
+  display_name: Python 3 (ipykernel)
+  language: python
+---
+
++++ {"editable": true, "slideshow": {"slide_type": "slide"}}
+
+# BIDS Schema Tools Quick Start
+
+The `bidsschematools` package is a Python package that is bundled with the [BIDS specification](https://github.com/bids-standard/bids-specification/) in order to render the components of the specification document from the BIDS schema.
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+import bidsschematools as bst
+import bidsschematools.schema
+```
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: skip
+tags: [hide-cell, remove-input]
+---
+# Hidden cell to import useful tools
+import os
+from upath import UPath
+from pprint import pprint
+```
+
++++ {"editable": true, "slideshow": {"slide_type": "slide"}}
+
+## Schema loading
+
+Schemas are loaded with the `load_schema()` function. The default schema is the one that is bundled as part of the package:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+schema = bst.schema.load_schema()
+```
+
++++ {"editable": true, "slideshow": {"slide_type": "subslide"}}
+
+In the BIDS repository, the schema source is a subdirectory of YAML documents that need to be compiled before they can be used. Passing such a directory into `load_schema()` will perform the compilation:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+# Build from local repository, or else set `BIDS_SPEC_REPO` environment variable
+spec = UPath(os.getenv('BIDS_SPEC_REPO', UPath(os.getcwd()).parent.parent.parent))
+schema_from_directory = bst.schema.load_schema(spec / 'src' / 'schema')
+```
+
++++ {"editable": true, "slideshow": {"slide_type": "subslide"}}
+
+`load_schema()` can also load a precompiled JSON schema document, such as can be found at <https://bids-specification.readthedocs.io/en/latest/schema.json>.
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+schema_path = UPath('https://bids-specification.readthedocs.io/en/latest/schema.json')
+schema_from_json = bst.schema.load_schema(schema_path)
+```
+
++++ {"editable": true, "slideshow": {"slide_type": "slide"}}
+
+## Schema organization
+
+The schema has three top-level subdivisions (`objects`, `rules`, and `meta`) and also contains its own version and the version of the BIDS standard that it encodes:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+print(list(schema.keys()))
+print(f'BIDS-Schema version: {schema.schema_version}')
+print(f'BIDS version: {schema.bids_version}')
+```
+
++++ {"editable": true, "slideshow": {"slide_type": ""}}
+
+Note that the schema provided by `load_schema()` is a [Namespace](#bidsschematools.types.namespace.Namespace) object, which is able to access fields with dot notation (`schema.bids_version`) as well as index notation (`schema['bids_version'])`.
+
++++ {"editable": true, "slideshow": {"slide_type": "subslide"}}
+
+We can see the general structure of the schema by listing keys at the second level:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+list(schema.keys(level=2))
+```
+
+```{code-cell} ipython3
+schema['meta.associations']
+```
+
++++ {"editable": true, "slideshow": {"slide_type": "fragment"}}
+
+The `objects` subschema contains definitions of data and metadata used throughout BIDS, while the `rules` subschema contains definitions of constraints that may be validated. `meta` contains definitions that are essential for validation.
+
++++ {"editable": true, "slideshow": {"slide_type": "subslide"}}
+
+To see how these sections interact, consider `rules.files.raw.func.func`, which contains the valid entities, datatypes, extensions and suffixes for functional neuroimaging files:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+pprint(schema.rules.files.raw.func.func.to_dict())
+```
+
++++ {"editable": true, "slideshow": {"slide_type": ""}}
+
+We can look up the suffix definitions in `objects.suffixes`:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+pprint({
+    suffix: schema.objects.suffixes[suffix].to_dict()
+    for suffix in schema.rules.files.raw.func.func.suffixes
+})
+```
+
++++ {"editable": true, "slideshow": {"slide_type": ""}}
+
+Note that suffixes are duplicated in the `value` field. Because suffixes are valid identifiers, this generally does not cause problems, and `objects.suffixes[suffix]` is a shorthand lookup.
+
++++ {"editable": true, "slideshow": {"slide_type": "subslide"}}
+
+This isn't true in all fields, for example, in extensions:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+schema.objects.extensions.nii_gz
+```
+
++++ {"editable": true, "slideshow": {"slide_type": ""}}
+
+In this case, a lookup table needs to be built on the fly:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+ext_lookup = {ext.value: ext for ext in schema.objects.extensions.values()}
+pprint({
+    ext: ext_lookup[ext].to_dict()
+    for ext in schema.rules.files.raw.func.func.extensions
+})
+```