Cljdoc alpha

documentation

#1

Hey everyone! :wave:

Over the last months I’ve been working on cljdoc, a platform to build, host and view documentation for Clojure/Script libraries. Some notable capabilities:

  • Platform Aware, i.e. documentation covers both platforms, .clj and .cljs.
  • Versioned, i.e. old versions are kept available
  • It’s A Database. Enabling many more interesting use-cases down the road.
  • Support for non-API documentation. You can define a tree of articles and provide it via your Git repo.
  • Hassle-free for library authors.

The homepage has all the information and some further links.

In the long run I hope that this platform can help drive improvements to documentation in the Clojure ecosystem. I’d love to see docsets for documentation browser apps, live examples right next to documentation. I’d love to see the Clojure community be a place where other communities draw inspiration from for their own documentation tooling.*

Please give it a shot and let me know what you think!


PS. I’m considering opening an org on OpenCollective to ensure this is a sustainable effort. For our application we need more stars on GitHub :wink:

* Shout out to https://docs.rs and https://hexdocs.pm for being an inspiration for this project.


#2

The homepage link is broken


#3

Are you sure? It’s working fine for me.


#4

This looks good so far.

If I may, it would be nice that instead of seeing an empty page when opening a project / library to instantly display the README, if it is available in that project.


#5

Yeah, that’s a good idea. Deployed :rocket: (commit)


#6

This is a great idea. Hopefully it can become a useful resource. I think it’ll be a great way to discover good libraries as well in the future - knowing that they have good documentation is at least a indication of quality.

Just one question - if the project documentation articles are in a separate repo, is it possible to refer to that repo inside the edn config file?


#7

Currently that’s not possible. I personally think there is value in versioning documentation alongside code but would be curious to get more context around how you would make use of that…


#8

I was just curious, as I know some projects that I use have documentation is separate repositories, e.g keechma - https://github.com/keechma/keechma-docs, https://github.com/shadow-cljs/shadow-cljs.github.io.

Was just wondering whether it would be possible to add projects like that without having to change the current documentation websites/processes.


#9

Got it, thanks! :slightly_smiling_face: 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).


#10

Well done. Is there a canonical way to link to Cljdoc from a project repo, like a badge or something? At the moment I’m using a direct link.


#11

Not yet but definitely intending to have this kind of thing. In the meantime, maybe this shields.io badge is a good start?

https://img.shields.io/badge/cljdoc-1.0.0-blue.svg

#12

Looks great in blue https://github.com/l3nz/cli-matic


#13

This is so awesome! A minor nitpick though - the embedded links (in README.md) are probably not rendered correctly, e.g. here: https://cljdoc.xyz/d/preflex/preflex/0.4.0/doc/readme/

Shantanu


#14

You’re right, sorry I was behind a proxy that weirdly doesn’t accept that connection and isn’t clear about it :sweat_smile:


#15

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 :raised_hands:


#16

This is great.

What I miss is a link somewhere to return to the root of the website (for example from https://cljdoc.xyz/d/reagent/reagent/0.8.1/doc/readme/ we need a link to go back to https://cljdoc.xyz)


#17

Fixed, the “cljdoc alpha” badge now links back to the homepage:


#18

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.

See it in action here: https://cljdoc.xyz/d/reagent/reagent/0.8.1/api/reagent.core
And note that all links are tied to a specific git revision, not simply master. :slight_smile:


#19

Fantastic! Works really well


#20

Some features shipped recently:

  • Build logs: overview & individual
  • 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 :sweat_smile:

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! :slight_smile:

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.

See you around :wave: