Hi! This project has been in the works for very long, but now it’s feature-complete.
(tl;dr example of the result • more examples)
I’ve been disgruntled by the fact that documentation for Crystal libraries is always being fit into the mold of the API doc generator, which forces just an alphabetic listing of all classes, while an actual usage manual is often either missing or heavily disconnected. That’s not the generator’s problem, it’s doing its job, but there wasn’t any alternative when more is wanted.
Well, now you can do more. I’m presenting a solution to do both the API docs and the textual docs within one MkDocs site, with the ability to intertwine the two halves arbitrarily (or not).
https://oprypin.github.io/mkdocstrings-crystal/
(don’t forget to leave a star and follow releases, as I’ll be posting updates there ;)
Another issue this solves is style customization: adding your own CSS becomes very natural, in addition to the numerous customizations that MkDocs themes themselves have.
Yes, this is implemented in Python, but sometimes you just have to defer to more mature tooling and take advantage of what’s out there.
You may have noticed that I had migrated Crystal’s doc book to MkDocs. This is actually different – now one can also migrate their API docs to MkDocs :) (no such plans for the main site though!)
Thanks to @straight-shoota for his early vision on doc JSON.
Thanks to @watzon and @Blacksmoke16 as early adopters.
And thanks to upstream projects
pawamoy/mkdocstrings (particularly @pawamoy for tight collaboration and inspiration for all this),
mkdocs/mkdocs, squidfunk/mkdocs-material, Python-Markdown/markdown, facelessuser/pymdown-extensions, pygments/pygments
I’m jealous of your docs!! (in a more positive way: I’m inspired by your docs ;))