It’s been a while that I posted an update here. Instead I recently just shared new stuff in the #cljdoc channel on Slack as it got released. But since not everyone is following along there and a lot of stuff has been shipped and improved over the last months I figured I might post a more long-form update here as well.
New & Improved Features
Much better documentation for library authors and users.
Until recently there were no guides for people to start using cljdoc. There were some pointers here and there but no one-stop guide to get going. Now we have guides for library authors and users pointing out the most important stuff.
Offline documentation bundles.
I’ve said it a million times and I’ll say it again: I’m a huge fan of tools like Dash. They provide documentation on different language ecosystems in a streamlined user experience — and — they work offline. Cljdoc now also provides offline-bundles to download. I’m also actively working with he creator of Dash to integrate cljdoc as a third-party source.
Article “Inference”.
Until recently you had to add a doc/cljdoc.edn file to your project if you wanted to incorporate any Markdown/Asciidoc files beyond your Readme. While this configuration is still handy in more advanced cases you can now also just dump those files in your doc/ directory and they’ll be incorporated into your documentation. They’ll be sorted alphanumerically so prefix the with 01- to achieve the order you want. Or just provide a doc/cljdoc.edn and benefit from additional features like nesting. See the docs on Articles.
Much improved multi-platform support.
If any aspect of a var or namespace differs across it’s supported platforms those differences will now be highlighted. This applies to arglists, docstrings, source URLs etc. See re-frame.interop for a namespace where this applies.
Faster badges.
If anyone has noticed their badges loading slowly, that should be fixed now by proxying to a new service called badgen (previously shields.io was used).
A service to access Clojars stats.
While not a next-week type thing I’d like to incorporate download stats and other information into cljdoc. A step in that direction has been made by creating a public service to run specific queries over Clojars download stats. Contributing is as easy as writing SQL! Also there’s probably a lot of optimisations to make things faster.
A new, much more beautiful and useful website and logo. The website now points to all kinds of relevant pieces of documentation and highlights core features of cljdoc.
A Roadmap
Obviously it’s a roadmap without dates but there’s still some interesting stuff that might be coming up. Spec integration, user-contributed examples, a new storage layer etc.
Check out the roadmap on GitHub and consider contributing if anything sounds worthwhile and/or interesting to you
Give it a shot!
If you maintain or contribute to a library consider taking a closer look at cljdoc. It’s already pretty awesome and it’ll only get better (no bias here ). If you’re a user of Clojure libraries cljdoc provides human-friendly docs for all Clojure libraries out there; so if you ever use a library that doesn’t provide it, check cljdoc.
What’s the relationship between clojuredocs and cljdoc? As I understand, the former is strictly for clojure.* docs and the latter is directed more towards community libraries. Do you think the two should co-exist together? Maybe some kind of integration is desirable, e.g. a shared database of examples?
cheat.sh adapter maybe? Haven’t looked into the implementation of that, just an idea.
Would be awesome if you could search for functions within libs. And if just like clojuredocs, you could add examples and notes to each function doc. And since you also include the readme style docs, could be fun if those could also have examples and notes added to them.
I think literate programming is an interesting technique that can be very useful, especially for more experienced developers. Newcomers may easily be overwhelmed by the level of detail though. I think there’s a lot of cool things we can do but I would be curious where you see the biggest value-add of literate programming before going deeper into this.
There is no relation between the two projects but as support for examples is added to cljdoc an open repository of some sort will be established and as licenses permit we will integrate examples from clojuredocs.
Your observation about clojuredocs being more focused on clojure.core and cljdoc being more focused on libraries is correct as well. Trying to support all libraries might require cljdoc to make some generalisations that don’t work well for clojure.core but we’ll see how that goes. In the meantime here’s what docs for clojure.core look like just in case you were wondering
Would love to see this kind of stuff pop up. It might be tricky because you’ll have to address from libraries > namespace > var which might make this a bit cumbersome but certainly possible.
Definitely coming soon. I have some ideas for a v1 of this that might even be relatively quick to implement.
Definitely agree about adding examples/notes to vars — would be curious how you imagine this to work with more text oriented stuff though. @arrdem has some interesting ideas on this with his stacks project but it seems to be going in a direction of “run your own documentation server” which is something I want to avoid. (The whole purpose of cljdoc is to take that kind of stuff off of library authors.)
For searching, I can really recommend Algolia, which is a paid service that is hard to beat in terms of ease of integraiton. But they might do give you free API calls if you ask: https://www.algolia.com/. Algolia powers https://hn.algolia.com
I think a good use-case for literate programming is writing interactive documentation. First, it’s always up-to-date, because you’re actually running all the code snippets you’ve put into your docs. Second, it’s very easy to get started with: just create a namespace, add a couple of examples, write a couple of comments - voilà, you’ve already got something you can build upon! I think sometimes starting writing docs can be a bit intimidating, you know what I mean? So people postpone writing it till they make a “proper” release, stabilize the api, etc. As a result, the docs and the code are mostly out of sync. Contrast it with the approach that tools like marginalia (can) enable: you can literally start by writing example-based docs (“programming by wishful thinking”), and then hack until the impl matches the docs. Also, I think example-based tutorials are the most effective form of documentation when you want to get started with a library quickly.
And of course it would be twice as cool if you could actually interact with and change those snippets while you’re reading the doc.
(Obviously, literate programming can also be useful when you’re reading the implementation, but since cljdoc is focused on, well, api docs and not implementation, I’m not sure if you’re interested in that. But it would be nice to be able to publish annotated source along with the docs, so you can quickly jump from function definition to the corresponding paragraph in the source, and maybe to the specific line in the file on github (so you can comment it) too.)
Personally, my pet complain about “normal” docs (like in the one you use in Cljdoc) and something I like about Marginalia is that it’s true you have access to the functions in a namespace, but functions without context are harder to understand. Function-based tools will allow linking to functions, but will sort them alphabetically (therefore losing context - the helper you write just before the actual function). And no specs in sight.
I guess that there are ways to document and properly format namespaces, but I admit my ignorance there. Maybe this is a tutorial that should be on Cljdoc
I think @danielcompton suggested before to provide different sorting options, e.g. sorting by occurrence in a namespace. I’m also having some ideas about viewing function source inline.
Specs will come eventually too
We could provide ways to add more structure to API docs using metadata but my intuition is that very few people will use that if at all. I’m more interested in automatic structuring, some raw ideas below:
highlight cars that are more documented than other vars in namespace
highlight vars that are not used in namespace they are defined (likely intended as API)
The drawback to these kinds of approaches is that they might actually be misleading in some cases. There’s also a github issue about this (check the Hammock label).
If I could influence documentation in one way, it would be to do away with alphabetical ordering. We’re already on a computer–you don’t need alphabetical ordering to help you find something like you would in a printed document. This is just a hold-over from another era.
Having relevant functions next to each other and sorted in a semantic way would single handedly fix so much documentation.
@jmlsf@didibus I agree and have to admit I didn’t put a lot of thought into the alphabetical sorting, it just seemed like “the thing to do” — but you’re right sorting by line number they occurred on makes a lot more sense and can provide some nice additional context.
