Documentation/generating documentation

[simon-brooke]

Usually my first step in understanding a new codebase is to write documentation for it :-)

I've been experimenting with integrating Codox and haven't yet found a satisfactory way to proceed. I'm raising this now because if you feel there is a better way to generate documentation I'd prefer to work on that, but if you agree that Codox is the right way to proceed I'll keep worrying at this until I do make it work.

Adding codox to the root deps.edn thus

:codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}}
                   :exec-fn codox.main/generate-docs
                   :exec-args {:source-paths  ["libs/kit-core/src" ;; "libs/kit-generator/src" "libs/kit-hato/src"
                                               ]}}

feels like the right way to go because it would produce a single linked web of documentation, but I haven't (yet) made it work - it fails with multiple errors of the general form:

(base) simon@mason:~/workspace/kit$ clojure -X:codox
Could not generate clojure documentation for kit.config - root cause: java.io.FileNotFoundException Could not locate kit/config__init.class, kit/config.clj or kit/config.cljc on classpath.
java.io.FileNotFoundException: Could not locate kit/config__init.class, kit/config.clj or kit/config.cljc on classpath.

Adding codox thus to the deps.edn of individual libraries does work, but, of course, generates isolated documentation webs for the individual libraries instead of a single integrated web:

 :aliases {:codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}}
                   :exec-fn codox.main/generate-docs
                   :exec-args {:source-paths  ["src"]}}}

[jwhitlark]

It wasn't immediately clear to me that you were referring to the kit project itself, as opposed to making codox available to a generated project. (The latter would work great as a kit module, IMO). Since kit seems to be run from clj-new, it's not clear to me how you would run codox on kit itself.

I'd suggest updating your comment to make it clear that you're adding it as an alias, which you obviously are, from the error message. Just to make things clearer.