Got it, thanks! It’s technically possible to enable this kind of thing but one thing that works fairly well when the docs are stored with the source is linking Git revisions to Maven/Clojars releases. This allows us to show documentation appropriate for a given version instead of just showing the latest (possibly with API docs that conflict this non-API documentation).
While possible this kind of linking would become more tricky when done across multiple repos.
I hope this makes sense! A related discussion also came up in a GitHub issue (there are situations where you want to update articles after a release has been cut).
The link isn’t rendered correctly because there is no tag in the corresponding git repo for version 0.4.0.
We could fall back to master for this case or simply throw an error. Will look into it. Thanks for bringing this up and glad to hear this is useful to you
Just deployed some code that adds source-links to projects that are linked to GitHub properly (git tag or sha in pom.xml). Unfortunately the change requires a rebuild of documentation to take effect so it won’t be available for all projects immediately.
Articles now have an “Edit on GitHub” link at the end of the page (example)
If you properly specify your SCM url, we show links to source for each var.
These links are tied to the specific Git revision for the given version (example)
Support for -SNAPSHOT releases
Lots of bugs introduced & fixed
If you would like to contribute, there are several issues tagged as “Good First Issue”.
If you’d like to contribute but none of these tickle your fancy… join #cljdoc on Slack and say hi!
There’s also a couple of larger things to think about: data model + storage & coming up with innovative twists on documentation that make it more useful. (Think emphasizing well documented vars/namespaces, examples, etc.)
I’ll personally focus on two things:
Tracking releases on Clojars. In order to build docs for every release on Clojars we need to know when new releases are published. Clojars doesn’t have a datafeed for this and I’ll try to either contribute that to the Clojars API or work with their search API if it turns out sufficient.
Provide offline bundles. I’m in contact with the creator of Dash (my favorite documentation browser) and it seems that we might get to integrate cljdoc sooner rather than later. As far as I understand this also means cljdoc docsets will be available for Zeal - a cross platform OSS alternative.
If you end up adding the badge to your projects please post it here, would love to see it in the wild
Since a few days we’re also auto-building documentation for releases as they are published to Clojars, it’s not instant (yet) but they’ll get there eventually.
If you have any feedback/ideas/thoughts please tell me here or in this GitHub issue.
I think the issue is resolved. The cause was probably that when the release was pushed to Clojars and the build got triggered you didn’t yet push the respective commit (referenced in pom) to GitHub. This issue occurs sometimes, I think for the near future I’ll introduce a minor delay (10min) before starting the build to give people enough time to push their commits as well.