Fork me on GitHub
#polylith
<
2021-04-25
>
wactbprot13:04:03

Hi, I try to build some documentation using codox by clj -A:dev -X:codox in a polylith ws. The ws contains several components all created with poly create component name:example. The problem is that codox does not find any namespaces and emits an empty index.html. I tried several :source-paths configurations without success. Any advice would be greatly appreciated.

seancorfield19:04:10

I don't see any docs on the Codox site for running it via the CLI. What is your :codox alias and how are you providing the Codox configuration?

seancorfield19:04:11

I just ran the following against our Polylith code and it produced documentation just fine:

$ clojure -Sdeps '{:deps {codox/codox {:mvn/version "0.10.7"}}}' -X:dev codox.main/generate-docs :source-paths '["bases/google-search-cli/src" "components/google-search-console/src" "components/seo-keyword/src" "components/site/src"]'
The :dev alias is for Polylith as usual. I provided the rest on the command-line so it could be seen easily.

seancorfield19:04:11

I just ran the following against our Polylith code and it produced documentation just fine:

$ clojure -Sdeps '{:deps {codox/codox {:mvn/version "0.10.7"}}}' -X:dev codox.main/generate-docs :source-paths '["bases/google-search-cli/src" "components/google-search-console/src" "components/seo-keyword/src" "components/site/src"]'
The :dev alias is for Polylith as usual. I provided the rest on the command-line so it could be seen easily.

wactbprot19:04:58

Thank you for the answer. The alias is:

:codox {:source-paths ["components/stmem/src"
                        ;; and variations of that
                        ]

                    :extra-deps {codox/codox {:mvn/version "0.10.7"}}
                    :exec-fn codox.main/generate-docs
                    :exec-args {:language :clojure
                                :output-path "docs"}}
So the :source-pathseem to have the same structure as in youre command line example.

seancorfield19:04:00

You need :source-paths inside the :exec-args map.

seancorfield19:04:44

When you use -X, the command-line arguments are parsed and passed as part of the :exec-args hash map.

seancorfield19:04:38

In your deps.edn, :source-paths is at the same level as :extra-deps etc and therefore is presented as an option for tools.deps.alpha (and it'll be ignored as unknown).

seancorfield19:04:11

^ @wactbprot does that make sense?

wactbprot19:04:12

Yes, makes sense if you explain it. Thank you very much. I find all the tools.deps stuff hard to understand.

seancorfield20:04:49

It def. doesn't help that all of Codox's docs refer to Leiningen and so all of the config examples are about project.clj which inherently provides options to plugins.

wactbprot20:04:07

Yes, but it's the same for most of the libs out there so far.

wactbprot20:04:58

Thank you again!

seancorfield20:04:53

Happy to help. We stopped using lein years ago at work. We switched to boot in 2015 and then to the CLI/`deps.edn` in 2018.