Spec-aware documentation tools

Since spec came out, my life as a Clojure programmer was definitely changed. I use it extensively and end up encoding a lot into specs - that end up documenting a lotof the pre- and post-requisites for my fns. Too bad that my docs (that I usually build with Codox) happily ignore them. Is there anything that will create decent documentation with specs?

2 Likes

autodoc (which is used for Clojure itself and contrib libs) does, but it is admittedly much harder to use than codox.

Example data specs: https://clojure.github.io/java.jdbc/#clojure.java.jdbc.spec

Function specs: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/defn

Having spent quite a bit of time hacking on autodoc in the past, the effort required to really make it accessible these days is pretty large, which is unfortunate as it does a lot of stuff really well.

Or if someone wanted to take direction from it and add to something like codox, the important bits can be found here:

3 Likes

Tried “lein autodoc” but after having to patch project.clj for requiring http sources (in 2020? ouch) and downloading a scary amount of stuff, it just dies trying to run a temporary file.

The version used to build docs for Clojure and the Contrib libraries is substantially different from the Leiningen plugin version I suspect. See all of the changes that Alex has been making: https://github.com/tomfaulhaber/autodoc/commits/master

You could try running Autodoc manually, based on the documentation in that repo?

1 Like

Thanks for bringing this up.
I created an issue for clojurephant as well (a gradle build plugin for clojure)

1 Like

Cljdoc has a desire to support that but it is a though nut to crack. Right, @martinklepsch?

At least with spec v1 I didn’t find a good solution. But maybe somebody else will if they set some time aside to think it through. Would be happy to 1-1 chat with people that are interested in contributing here.

From this GitHub issue

Currently specs don’t contain any metadata about where they have been defined. This makes it impossible to tell from which artefact a spec originates. Tying specs to artifacts is important to:

  • only extract specs from the artefact under analysis and not it’s dependencies
  • avoid conflicts between identically named specs at the storage layer

Potential solutions:

  1. Wait until issues mentioned here are addressed.
  2. Fork spec, implement metadata features and inject our version into the analysis runtime.
  3. Store specs in the global namespace and hope conflicts aren’t too problematic. Note that the same spec packaged in two different versions of the same artefact will also introduce a conflict.