bids-validator

bids-validator copied to clipboard

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.