Idea: Split README.md into separate files per Validator and use a processor to generate the main README.md

[pano9000]

Quick Idea I had, because I noticed how horrible it is to check for differences in the huge README.md:

How about instead of having one huge README.md that will constantly cause merge conflicts that are quite hard to catch (at least that is my feeling), we instead have one separate README.md per validator, that is then just "referenced" or "linked" into the main README.md.
I feel like this could make life for PRs quite a bit easier and less error prone

If there is any interest in this, I would spend some time to research for some solutions here, as this sadly does not seem possible with "regular" markdown out of the box, but can be achieved with some additional processing.

A few ideas can be found in this stackoverflow thread:
https://stackoverflow.com/questions/4779582/markdown-and-including-multiple-files

Any thoughts on this?

[WikiRik]

My idea was that eventually with TypeScript it would be easier to generate a API reference (with typedoc for example), hosted with GitHub Pages, which can reduce the need for such a detailed README

[pano9000]

createing an API reference with a whole doc processing behind it, would be of course even nicer, true - but I guess also more work to setup?

But I think that should be the end goal here at some point, as working with such docs is a lot more fun than with a regular huge README.md, where you don't really have the place to fully express everything in great detail.

regarding Typescript: were there any plans to move this project to TS? I only saw an isse about it, but it looked like the idea was shut down.

[WikiRik]

We've set up typedoc for sequelize a few months back and that was not too much effort. Granted we had jsdoc in the files as well, but moving info from the README to the validator files would not be too much work I think. That would also be a start before we migrate parts to TypeScript.

About TypeScript; I think there are still people interested in that. As long as we ensure that we transpile in the same way as we publish now so that functionality wise nothing changes. TypeScript is used a lot more now and having up to date types adds a lot of benefit, also with the VSCode intellisense. And since we do not have a complex project, the types can also be quite easy and contributing to the project is not much harder than it currently is.

[pano9000]

I don't have any real strong feelings about Typescript (nor any practical experience with either so far), so can't really give any valuable input on that, but I did find the typescript issue, where I guess this discussion could be continued: #1271