This site hosts API documentation generated using the built-in documentation generation tool, with some post processing. The hope is that this alleviates the need for each individual project to setup a website to host documentation using (for example) GitHub pages, and makes it easier to find API documentation.
Features:
Builds docs for every tagged version
Builds docs for nightly branches (main, etc)
Automatically finds new versions/updates nightly branches once per day
Links to source code and shards.info
Supports any git host that follows the format domain.tld/username/project
To-do:
Add page listing all repos
README badges
Performance improvements via nginx / CDN
General UI polishing
Mercurial / Fossil support
Better doc generation queue page
All suggestions and feedback welcome!
Note: all of the documentation is currently in the process of being rebuilt to a newer format, so until that’s done you may see docs still showing the older format. This should be done in a few hours.
As soon as Fossil support is in, I’ll definitely be using this ^_^ It’s a tiny bit annoying to have to manually build and upload docs to my webhost right now.
I wonder if would be possible to put the GTK4 bindings docs there. The main problem is because the docs are generated by crystal doc from generated files, and to generate these some extra dependencies are needed.
Maybe it would require the repository to docs checked in in the repository in JSON format like api-docs.json… and if crystal doc could take that JSON as input to output HTML.
BTW I found a CSS bug in crystal doc gen dark mode.
What are the extra dependencies? I could add them to the doc generator. I also thought about adding a .crystaldoc.yml to allow people to specify what non-crystal dependencies they need but that’ll probably come at a later point.
Thanks for finding the bug! What browser/os are you using?
It currently does not - I’m only saving outputted docs from the doc generator. I could add support for that soon though I’d just be worried about security stuff with allowing arbitrary files. A workaround would be having the image link point to wherever it’s hosted but that’s not ideal either.
The problem is: it depends on what library the bindings are for.
For GTK4 bindings the (ubuntu) dependencies are:
libgtk-4-dev
gobject-introspection
gir1.2-gtk-4.0
libgirepository1.0-dev
But for other bindings there are another dependencies for the respective libraries (e.g. libadwaita, GtkWebKit2, GtkSourceView, libVte, etc…), it doesn’t need the shared library itself, but it needs the .gir and the typelib files that are used by gobject introspection library to give information about the library and let the generator be able to generate the bindings.
Another issue is that it’s not just install the dependencies and run crystal doc, you need to:
install dependencies
run shards install
run ./bin/gi-crystal --doc to generate the bindings with documentation
then run crystal doc.
This is why I thought about having just the JSON file generated by crystal doc checked in in the repository and let crystal doc be able to build the HTML documentation from it, so all the weird steps needed are moved out of crystaldoc.info scope.
Can we get some badge to include in projects readme?
General concerns on a central service/repository:
This is not the first attempt for a central doc service for crystal. I am not sure what where the problems with the former one(s?). But I wonder if the hosting and computing cost would become a problem. Was there an analysis regarding how long this is feasible in a free tier? Or how much sponsorship is needed for the current community if all the docs are built?
In that regard, to reduce the processing costs I wonder if the queue could be delegated to each project and the results of crystal docs be sent to the server. Maybe the results should not be plain html, or there should be some kind of verification that the output has not been tampered.
A related point is that even generating docs requieres some sandboxing or bad things can happen. As macros anything can happen there. Where there any measures taken in this regard?
Going a step further even a central index of documentation might not need central processing and hosting of them. For example if each shard gives access to store the doc results and metadata in some well known branch, then you need to only keep an index of which shards were registered.
There has been lot’s of efforts through time to have a nice documentation system for crystal, but definitely there is room for that last mile to make them more available without building it yourself. So thanks for pushing the current state on that aspect!
Other central doc services have existed before, but I believe they didn’t succeed due to not realizing the full scope of what this would require, or due to the developers/maintainers moving on for a variety of reasons. The performance requirements for this aren’t that high - for instance I’m running this on a $12 VPS currently with 2GB RAM and 1 vCPU, and it was able to churn through generating all 1000 repos in about a day. Most of the time the doc builders are doing nothing and the site is just serving static content. The cost of the VPS is something I’m perfectly fine covering, though this cost may go up if I decide to start using CDNs for better coverage around the world.
One design consideration for me with this was that it should be as simple as possible for people to get their docs generated on the website, as any additional steps could be a deterrent. I can maybe consider allowing certain projects to upload docs (like GTK4 Binding ones) but that’d have to be on a case by case basis.
I’m currently sandboxing docs generation with firejail but I’m probably going to move to Docker (as that’s what docs.rs uses)
That may be good but it has the downside of not giving a cohesive experience. It may be better instead to make it super simple for someone to setup a new instance of crystaldoc if, for some reason, they want only certain shards, etc. That way, if something does happen to my hosting it would be really easy for the community to pick it up and move it somewhere else.
