Document how to use with deps.edn

[metasoarous]

Hello

I'm considering using codox to document Oz & Semantic CSV, but Oz uses clj & deps.edn, and I will be moving Semantic CSV to the same. I see from #163 that codox doesn't require leiningen, but I don't see any documentation about how I might use it with the deps.edn toolchain.

It seems like I can just manually call codox.main/generate-docs, likely even from a deps.edn alias, but it would be nice to see some examples of this.

Thanks!

[metasoarous]

I tried doing this using the new -X option, with an alias like so:

{...
 :aliases {
           :docs {:extra-deps {codox/codox {:mvn/version "0.10.7"}}
                  :exec-fn codox.main/generate-docs
                  :exec-args {:language :clojure
                              :output-path "docs"}}
           ...}}

In theory, this should be a pretty good option for doing this. However, I get the following:

% clj -A:clojupyter -X:docs                                                               :( 1 20-11-22 - 0:47:47
Exception in thread "main" java.lang.Exception: Could not load codox writer codox.writer.html
        at codox.main$writer$fn__816.invoke(main.clj:16)
        at codox.main$writer.invokeStatic(main.clj:12)
        at codox.main$writer.invoke(main.clj:9)
        at codox.main$generate_docs.invokeStatic(main.clj:122)
        at codox.main$generate_docs.invoke(main.clj:116)
        at clojure.lang.AFn.applyToHelper(AFn.java:154)
        at clojure.lang.AFn.applyTo(AFn.java:144)
        ...
        at clojure.main$main.doInvoke(main.clj:561)
        at clojure.lang.RestFn.applyTo(RestFn.java:137)
        at clojure.lang.Var.applyTo(Var.java:705)
        at clojure.main.main(main.java:37)
Caused by: Syntax error compiling at (hiccup/page.clj:10:4).
        at clojure.lang.Compiler.analyze(Compiler.java:6808)
        at clojure.lang.Compiler.analyze(Compiler.java:6745)
        at clojure.lang.Compiler$InvokeExpr.parse(Compiler.java:3820)
        ...
        at clojure.core$require.doInvoke(core.clj:6007)
        at clojure.lang.RestFn.invoke(RestFn.java:408)
        at codox.main$writer$fn__816.invoke(main.clj:13)
        ... 24 more
Caused by: java.lang.RuntimeException: No such var: util/raw-string
        at clojure.lang.Util.runtimeException(Util.java:221)
        at clojure.lang.Compiler.resolveIn(Compiler.java:7387)
        at clojure.lang.Compiler.resolve(Compiler.java:7357)
        at clojure.lang.Compiler.analyzeSymbol(Compiler.java:7318)
        at clojure.lang.Compiler.analyze(Compiler.java:6768)
        ... 89 more

(Note that I'm adding -A:clojupyter so that certain optional namespace can be loaded properly).

Curiously, if I just run a REPL with clj -A:docs, I can require these namespaces without issue.

Any idea what might be going on here?

Thanks!

[weavejester]

It looks like you have a strange dependency issue with Hiccup, where the hiccup.page namespace is from 2.0, and the hiccup.util namespace is from 1.0. Try wiping the class files in your target directory.

[metasoarous]

Hi @weavejester. Thanks for the rapid response!

I will note that Oz is using hiccup 2.0.0-alpha2. Seems like that could explain the issue? But then strange that it's required without issue from the REPL. I did try nuking my target directory to no avail.

Is hiccup getting close to a non-alpha 2.0.0 readiness? Would it be feasible to update this dependency for codox?

Thanks again!

[weavejester]

Something seems strange in your build chain if you're ending up with compiled namespaces from two different versions of the same dependency.

Hiccup 2.0 is backward compatible with 1.0, so you could just manually force Codox to use Hiccup 2.0.

[metasoarous]

Thanks again for the quick response.

The problem here appears to be an issue with Clojupyter AOT/Uberjar compiling with an older version of hiccup. If I comment out the namespace which uses Clojupyter and leave clojupyter out of the list of dependencies, compilation works fine.

I'll submit a PR for an update to the README that documents how to use codox with deps.edn.

Thanks again!