The Crystal Programming Language Forum

New documentation site generator: mkdocstrings-crystal

Hi! This project has been in the works for very long, but now it’s feature-complete.

(tl;dr example of the resultmore 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

12 Likes

This project is honestly everything I’ve been looking for in documentation generation for Crystal. Thanks for being willing to accept my input!

Congratulations @oprypin! Amazing work you’ve done here :slight_smile: I’m jealous of your docs!! (in a more positive way: I’m inspired by your docs ;))

Hi everyone,

If you’re thinking “hmm maaaybe this could be nice for my project”, please just reach out. Could be anything from a quick question to me just migrating your site, as I’m interested in gathering critical mass and seeing different perspectives on what’s required.

(via these options or some other way)