Reconfigure API documentation for project because Codox won't locate namespaces in external modules

[Lambeaux]

The objective of this issue is to restore the Codox API documentation generation which was being published to Github Pages (the gh-pages branch).

Originally this project was using Codox to generate API documentation. The main.clj file for the docs generation, along with some troubleshooting code, looked like this:

(ns main
  (:require clojure.pprint
            [clojure.xml :as xml]
            [codox.main :refer [generate-docs]]))

(def sep (apply str (take 100 (repeat "-"))))
(defn- shout!
  ([data]
   (do (println sep) (println sep) (println data) data))
  ([msg data]
   (do (println sep) (println sep) (println msg) (println data) data)))

(defn- get-source-paths []
  (->> ["../klojure-catalog" "../klojure-deps"]
         (map #(str % "/src/main/clojure"))
         vec
         shout!))

(defn- project-info []
  (->>
    ;; Need to verify what mvn sets as working dir when building sub-modules
    (:content (xml/parse "../pom.xml"))
    (shout! (System/getProperty "user.dir"))
    (filter #(#{:artifactId :groupId :version :description} (:tag %)))
    (map #(-> [(:tag %) (first (:content %))]))
    (into {})
    shout!))

(defn -main []
  (let [{:keys [artifactId groupId version description]} (project-info)]
    (generate-docs)
    {:doc-files ["../README.md"]}
    :source-paths (get-source-paths)
    :name artifactId
    :package (symbol groupId artifactId)
    :version version
    :description description
    :namespaces [#"^(?!(doc|klojure)).*"]
    :metadata {:doc/format :markdown}
    :source-uri (str "https://github.com/djblue/" artifactId "/blob/master/{filepath}#L{line}")))

(-main)

Assuming mvn:codox/codox/0.10.7 and mvn:org.clojure/clojure/1.10.0 are on the build classpath, the above can be tested and the issue reproduced by running the following:

mvn clojure:run -Dclojure.script=src/main/clojure/main.clj

Several notes:

• The Clojure script itself can find files and follow paths just fine
• All the data is valid when sent to Codox's (generate-docs) function
• The docs are not being generated properly, as if no source code exists
• Tests were done with both absolute and various relative paths but did not produce results

Codox must be limiting itself internally to only the current module or build context's set of resources, either by a classloader or some other mechanism. Or additional functions need to be called since we are scripting around Codox

An alternate approach might be to setup a proper project.clj at the root, which can parse redundant info from the pom, and use that for the Codox declaration. Then using the Maven Exec Plugin we could invoke Leiningen to run the docs job (see compiling a leiningen project from maven for more on that). Here's an example of how the ring project does it.

Codox also supports markdown, so restoring it means any dependency analysis walkthroughs or "how-to" guides can also be published, linked, and referenced separately from GitHub.

Relevant links:

• https://github.com/talios/clojure-maven-plugin
• https://github.com/weavejester/codox#codox
• https://github.com/cljdoc/cljdoc (alternative to Codox but requires deployment on Clojars)