Spec-aware documentation tools

l3nz · June 17, 2020, 6:12pm

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?

alexmiller · June 18, 2020, 5:35am

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:

github.com

tomfaulhaber/autodoc/blob/master/src/autodoc/build_html.clj#L407-L447


(def key-pred*
  "A function for pretty-printing specs that take key-pred-forms"
  (formatter-out "~<(~;~w ~_~@{~w~^ ~w~^ ~_~}~;)~:>"))

(def spec-table
  "A modified version of the pprint code table that handles specs"
  (assoc @#'clojure.pprint/*code-table*
         'alt  key-pred*
         'cat  key-pred*
         'or   key-pred*
         'keys key-pred*))

(def ^:dynamic *keyword-ns* nil)

(defmulti wrap-dispatch
  "A wrapper for code dispatch that prints local keywords with ::"
  {:arglists '[[object]]}
  class)

(defmethod wrap-dispatch :default

This file has been truncated. show original

l3nz · June 18, 2020, 7:11pm

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.

seancorfield · June 18, 2020, 8:00pm

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?

ieugen · June 25, 2020, 12:36pm

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

HolyJak · June 28, 2020, 11:03am

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

martinklepsch · June 29, 2020, 11:28am

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:

Wait until issues mentioned here are addressed.

Fork spec, implement metadata features and inject our version into the analysis runtime.

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.

system · December 28, 2020, 11:28pm

This topic was automatically closed 182 days after the last reply. New replies are no longer allowed.