search

tomfaulhaber / autodoc

The robot to automatically generate documentation for Clojure code. Used to generate the API docs for clojure.org.
121 stars 26 forks source link

When running autodoc against ClojureScript's source code, empty output is produced #21

Closed bensu closed 8 years ago

bensu commented 8 years ago

Hi!

I tried to run autodoc against Clojurescript like this:

cs clojurescript
java -jar autodoc-0.9.0-standalone.jar --source-path=src

where autodoc-0.9.0-standalone.jar was generated by checking out 09ea736 and running lein uberjar. I'm getting warnings about the source paths not being in the class path:

./src/main/cljs/cljs/js.clj: failed (ex = java.io.FileNotFoundException: Could not locate cljs/env__init.class or cljs/env.clj on classpath: )

I uploaded the results here. What is weird is that even if it warns it failed to find the file, the docs are produced with the correct namespace Overview but without any vars.

If I then zoom in and make sure everything is in the classpath:

cd clojurescript/src/main/clojure
java -jar ~/OpenSource/autodoc/target/autodoc-0.9.0-standalone.jar

autodoc throws no warnings but produces the same type of output (ns overview found but no vars) for the namespaces under src/main/clojure.

Any idea on what could be causing autodoc to miss the vars?

Thanks

tomfaulhaber commented 8 years ago

This is the expected result. autodoc doesn't support clojurescript and there is already issue #16 for that.

The problem is that the way autodoc generates var information is by running an external instance of java that uses autodoc-collect to load all the namespaces in the project and inspect them. Since a clojurescript process has no clojure namespaces, there's no result (or rather an empty result).

To support Clojurescript (or any other variant), we'll need to create a version of autodoc-collect for clojurescript and teach autodoc how and when to use it. I don't think this should be too hard.

The other thing is that any work on clojurescript should be done using the current version of autodoc (not yet in clojars, but I hope to fix that soon) rather than 0.9.

tomfaulhaber commented 8 years ago

Oh, I misunderstood. You want to run this on the clojure code in clojurescript. I wouldn't really expect it to be working with 0.9, as I mentioned above.

bensu commented 8 years ago

So, just to be extra clear: the Clojure JVM code in the ClojureScript compiler can't be analyzed in 0.9.0 but will probably be supported in 1.0.0.

Thanks! I'll wait for for 1.0.0''s release then.

bensu commented 8 years ago

Hi Tom,

It was nice to meet you today!

I tried to runautodoc-1.1.0-standalone.jar (built from 0f59e30) on ClojureScript's source code:

java -jar ~/OpenSource/autodoc/target/autodoc-1.1.0-standalone.jar  --source-path=src

Exception in thread "main" java.lang.RuntimeException: EOF while reading
    at clojure.lang.Util.runtimeException(Util.java:221)
    at clojure.lang.LispReader.read(LispReader.java:246)
    at clojure.lang.LispReader.read(LispReader.java:196)
    at clojure.lang.LispReader.read(LispReader.java:190)
    at clojure.core$read.invoke(core.clj:3640)
    at clojure.core$read.invoke(core.clj:3638)
    at clojure.core$read.invoke(core.clj:3636)
    at clojure.core$read.invoke(core.clj:3634)
    at autodoc.collect_info_wrapper$do_collect$fn__1543.invoke(collect_info_wrapper.clj:87)
    at autodoc.collect_info_wrapper$do_collect.invoke(collect_info_wrapper.clj:86)
    at autodoc.autodoc$build_html.doInvoke(autodoc.clj:26)
    at clojure.lang.RestFn.invoke(RestFn.java:397)
    at clojure.lang.Var.invoke(Var.java:375)
    at clojure.lang.AFn.applyToHelper(AFn.java:152)
    at clojure.lang.Var.applyTo(Var.java:700)
    at clojure.core$apply.invoke(core.clj:630)
    at autodoc.autodoc$autodoc.doInvoke(autodoc.clj:102)
    at clojure.lang.RestFn.invoke(RestFn.java:425)
    at autodoc.autodoc$autodoc.invoke(autodoc.clj:76)
    at clojure.lang.AFn.applyToHelper(AFn.java:154)
    at clojure.lang.RestFn.applyTo(RestFn.java:132)
    at clojure.core$apply.invoke(core.clj:632)
    at autodoc.autodoc$_main.doInvoke(autodoc.clj:115)
    at clojure.lang.RestFn.applyTo(RestFn.java:137)
    at autodoc.autodoc.main(Unknown Source)

I'm having a hard time deciphering the error, but it might be related to the /tmp/collect-123123.clj file being empty. Am I missing something in the setup?

tomfaulhaber commented 8 years ago

@bensu Likewise!

Hmmm, this error usually means autodoc-collect has exploded in some way (and then swallowed the error which is annoying). The result is the empty /tmp/collect... file. (The error reporting could be way better here!)

I'll give this a run in the morning and see if it's something that I can fix with a config file or whether it's a problem with autodoc-collect.

tomfaulhaber commented 8 years ago

OK - a bunch of fixes but it's good to go now.

The best way to get doc in the short term (before we start building it to clojure.github.io) is to use the lein-autodoc to build the docs. This automatically picks up all the leiningen dependencies and such before looking at the code. See the README there for how to do this.

The next phase will be to automatically publish the docs to clojure.github.io.

bensu commented 8 years ago

What a great response time! Thank you!

I pushed a preliminary version of the docs to http://bensu.github.io/clojurescript-docs until they are pushed to clojure.github.io

I'll look at which namespaces and vars should be hidden.

tomfaulhaber commented 8 years ago

Great news, @bensu.

I'm going to close this issue now and we can coordinate further work through the issue in the ClojureScript Jira, CLJS-1446.