Documentation revamp

[koddsson]

I really like the documentation and I want to really try to avoid rewriting it's system but I think we should colocate it with the code in this repo as opposed to keeping it in a different repo. I also think we should generate most of the API documentation from the JSDocs. This way we don't change the code without updating the docs as well.

Here's a loose list of what I think we should do:

• Install ESLint and the jsdoc eslint plugin to validate that the jsdoc comments are in the correct format.
• Fix all the ESLint jsdoc issues.
• Use some sort of generator to generate the API site. I'd be happy to use Jekyll but maybe something like 11ty would suit us better?
• Add a CI check that validates that documentation is correct somehow or even deploys to a temporary host.
• Migrate the docs from the old repo to this repo and the new docs system.
• ???

What do you think?

@chaijs/core

[43081j]

it sounds like it could be a good idea but id be interested to see a poc or suggested solution

we did slip up slightly when releasing the new major and not updating docs, probably because they're decoupled

think we also need to review the docs as they are now to at least correct what the major release changed

[koddsson]

Here's a quick thing I threw up using jsdoc:

We could obviously tweak the styles and all that. And also make the markdown work and update all the docs like you said.

[koddsson]

I can fiddle with this some more and maybe put on a draft PR.