Clojurians Log v2
cljdoc
I'm currently building a Clojure wrapper for the ArrayFire tensor C/C++ library (https://github.com/lsolbach/arrayfire-clj). I've pushed a snapshot to clojars and tried to build the docs on cljdoc, which failed, because the ArrayFire library (libaf) is not available (see https://app.circleci.com/pipelines/github/cljdoc/builder/71048/workflows/b7d54133-60e9-441e-9532-005c4ab8adae/jobs/87422). Installing ArrayFire is quite elaborate, there's no recent package or maven package to install. Is there a way to skip the build and only generate the docs on cljdoc?
Hi @lsolbach! I have many cljdoc works-in-progress... one of them is building API docs staticly (https://github.com/cljdoc/cljdoc/issues/543). I think this would probably work for your use case. Although... it is still a wip.
Strict analysis as a default is totally fine for me. It has even caught some dependency problems in a release of mine once or twice. That's why I always generate the docs for a snapshot before releasing code. But in case of ArrayFire I don't see a reasonable way of providing it via dependencies. An option to disable the analysis would be the best, IMHO. arrayfire-clj also generates FFI binding functions for the C API of ArrayFire. But those are a 1:1 copy of the C API so the ArrayFire docs are fine and could be linked. These functions are not part of the API of arrayfire-clj, as they are low level and not integrated in the JVM/Clojure ecosystem. The rest of the doc should be static.
Interesting. So what would be shown where cljdoc normally shows API docs?
All the docs except for the macro-generated symbols in the FFI namespaces.
So everything that could be statically generated.
Oh, we might be using different terms. By "strict analysis" do you mean the current dynamic API analysis done today by cljdoc where namespaces are loaded to discover the API? And by "skip the build" do you mean skip the API analysis entirely? Maybe a picture will help:
I mean analyze the codebase statically based on the source code, so discover all vars in the source code. All vars generated at compile time by macros or otherwise will not be there because they are not present in the source code..
It's an analysis nonetheless, but it does not try to compile the code.
So the API is shown, but missing some vars which are not available by just looking at the source code. I could live with that for arrayfire-clj.
this analysis would be independent of any compile/runtime requirements of the project (e.g. missing libs or JDK mismatches).
Ah, thanks, I understand now. So this is what https://github.com/cljdoc/cljdoc/issues/543 is about. Perhaps I'll try to reboot that effort sometime soon.
Yes, I've read through that issue and it matches my problem.