Documentation

[effigies]

The README and API docs are not really sufficient. We should add proper documentation.

• User docs
  • Using the web UI
  • Using the CLI
    • Installation
    • Execution
  • Interpreting issues
    • Codes with subcodes
      • Missing sidecar keys
      • HED Errors
    • Schema-defined issues
      • Auto-generated doc mapping every issue to its location in the schema, with rendered YAML of containing rule
    • Validator-defined issues
      • Auto-generated doc with explanation of issue
• API docs (or just flesh out https://jsr.io/@bids/validator/doc)
  • Example uses
  • Full API listing
• Developer docs
  • Setting up a dev environment
  • Running tests
  • Structure of the code
  • The validator model
    • Validation context, how and where it's constructed
    • Walking the file tree
    • Inheritance principle

Some of this might be better to simply reference in the omnibus website, but some will be significantly easier to keep in sync with the validator by producing locally.

I would suggest ReadTheDocs. I think we could use https://github.com/mozilla/sphinx-js and https://www.sphinx-doc.org/en/master/usage/markdown.html to keep things more familiar to the potential contributor base.

[effigies]

Should add a section on the legacy validator. Can probably use bits of https://hackmd.io/fk9pCOVoRia0oFl1_opNHg

[Remi-Gau]

fo reference this is the current page about the validator in the bids website: https://bids-website.readthedocs.io/en/latest/tools/validator.html

[Remi-Gau]

ok with keeping most of that doc closer to the tool than in the main BIDS website

could definitely have the equivalent of a TLDR in the BIDS website and then point to the proper bids validator doc website section for more info.

[Remi-Gau]

random thought: one section that could be extracted on the website (especially if it is common to all validators - deno / legacy / python) is the section about bidsignore.

[effigies]

Had a quick stab at starting a sphinx doc site. It seems deno does not play very nicely with typedoc, so it might not be worth it. OTOH, we can just link out to https://jsr.io/@bids/validator/doc and make sure those are in good shape.

[Remi-Gau]

what is the typical thing javascript people use for doc? Docusaurus? Not sure if it makes sense to try it.

[effigies]

Docs are started here: https://bids-validator.readthedocs.io

what is the typical thing javascript people use for doc? Docusaurus? Not sure if it makes sense to try it.

The API is pretty limited, so I'm inclined to just use Sphinx for familiarity and link out to JSR. We can flesh out docstrings to improve that page.

[Remi-Gau]

vaguely related: bids-standard/bids-website#572

[dshattuck]

@effigies Thank you for all of the work on this. I am in the process of switching our BIDS App to use the new validator, which seems mostly straightforward.

One thing I think would be helpful in the CLI documentation for people migrating to the new code would be information on what options have changed from the legacy version. For example, it looks like --ignoreSubjectConsistency is no longer an option. We found this useful for some large datasets because the consistency checking used a lot of memory.

cheers,
David

[effigies]

Thanks @dshattuck. The --ignoreSubjectConsistency is missing because subject consistency checks are no longer a thing. They might be useful in a secondary tool, but we agree that they took too much memory and were too prone to false positives for them to be a valuable feature in the validator.

[effigies]

But noting changes to the CLI in the docs is definitely a good idea.