bids-validator
bids-validator copied to clipboard
bids-standard
improve docs --> automatically generated?
Most software packages of similar size and purpose as bids-validator have a comprehensive documentation. Meanwhile, we have a long README and a CONTRIBUTING file (which is not very visible).
What do you think about having dedicated docs build by some CI and then hosted on the gh-pages branch of this repo?
We could split the README into logical parts, improve the visibility of the CONTRIBUTING file ... and provide a good target place for future docs improvements.
Last but not least: Would it be possible to get an automatic API documentation generated from docstrings? I am not familiar enough with the JS ecosystem to say how common this is.
cc @rwblair @effigies
We have some JSDoc strings though they are far from complete and mostly aimed at developers working on the validator rather than users. Maybe something like GitBook with JSDoc so we can have some user facing documentation generated from a docs tree and use the JSDoc annotations to provide developer focused docs?
Developer focused docs would be a great improvement, because it would help us to recruit more contributors!
This just came up again in a separate email thread containing several BIDS BEP Leads, so this is still very much wanted and needed.
unpinning, as this has become less urgent, with the BIDS schema being the future of the validator. Resources should be directed towards documenting the schema and how to contribute to it.