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.

[koddsson]

@keithamus @43081j; I started writing an eleventy site derived from the JSDoc info and the chai plugins exposed in the npm registry API. I'm using PicoCSS for styling.

What do you think? I wanna ask now so I don't waste my time if you feel this isn't worth it.

Home page:

API method example:

I've also got fetching the plugins and outputting pages for them up and running, I just haven't started rendering out those yet.

[keithamus]

YES! Let's do it!

[43081j]

looks great. would love to sort out our docs for sure

they've gone a little stale over time. would be great to do this

[koddsson]

I've gotten most things working, but I was hoping to generate API docs from the JSDoc comments (and then eventually from TypeScript types as well). But all the examples are just for expect (see fail for example).

I want to derive the docs from the code so that we don't have as much drift from the docs and the actual code. But I might just punt on that for now and crib the old API docs, then I can start working on reworking the JSDoc comments to be more "parseable", with examples for should and assert and tests that assert that any given assertion has all the required examples and metadata.

[koddsson]

Here's the repo for what I got so far and a built version hosted on https://koddsson.github.io/new-chai-docs. I think it's pretty nifty, but happy to hear any and all feedback :)

[43081j]

is there a way we can have some kind of contents/navigation in the API docs?

for example, here:
https://koddsson.github.io/new-chai-docs/api/bdd/

it'd be good to have the full list of headings and be able to jump to them

these look great though 🙏

[koddsson]

is there a way we can have some kind of contents/navigation in the API docs?

for example, here: https://koddsson.github.io/new-chai-docs/api/bdd/

it'd be good to have the full list of headings and be able to jump to them

Yup! I have that working for https://koddsson.github.io/new-chai-docs/guide/ and you can use the navigation at the top of the page to jump to whatever you'd like. Should be trivial to implment for the API page as well.