Migrate/add an API documentation site based on MkDocs

[oprypin]

Includes version selector and auto-deployment to GitHub Pages. The URLs are fully backwards compatible.

Preview: https://oprypin.github.io/crystal-db/api/

The main thing that's up for discussion is the categorization on the left hand side. I thought it added a lot to the usability, but it's manual and done by me without any familiarity with "crystal-db", so maybe the categories need tweaking.

[straight-shoota]

Looks awesome :+1:

That manual editing of SUMMARY.md is unfortunate, but I agree that having these sections in the navigation is a great enhancement. So I'd prefer to rather have that instead of missing out on the structuring.

For the future we could consider integrating section tagging in the doc generator syntax to remove the gap between structure and content.

[z64]

I'm sorry if this is too critical, but I don't think this frontend is ready yet for documenting general code.

Overall presentation

The overall presentation feels like a step backwards in design. The headers are hard to read with low contrast and multiple font sizes. The body being in this quote block looking style gives a structure that doesn't feel apropriate; it feels more like a blog.

Compare to crystal docs, which has very distinct headers that gives all the structure it needs:

Another comparison, where we are missing the concise summary that more quickly helps me find my way. I am often searching for something first before learning about it - without the summary there is a lot more scanning / noise to go through.

I'm aware of the right-side ToC, but I don't feel this is adequate. We lose the short summary, at least.

Search

You can not search for methods with the same syntax that the compiler docgen has:

Maybe there is some other trick I don't know, but I have to expand the list and what I want is very far down:

Again, with crystal docs what I am looking for is the third item:

ToC on smaller breakpoint

If you open https://oprypin.github.io/crystal-db/api/ and are on a small breakpoint, you get this in the ToC bar. Until I realized I had to click the arrow on the upper left, I thought something was broken.. Can this UX be improved? We still have a ton of real estate on the sidebar, but at least a better button would be nice, or a text hint - I thought it was just going to close the sidebar.

There's some other things, but these were the biggest issues I found with this. The organized sidebar is nice. But in my opinion, the design problems here don't make it worth it. In the current state, I would rather see crystal docs improved to allow sidebar organization.

If we host them both then I guess that is fine, but this is :-1: from me if we are considering replacing the current docgen.