specify local path for API javadoc

[pw4ever]

CIDER 0.9.0snapshot (package: 20141227.1232).

This is more of a feature request than an issue.

The current javadoc-info logic (https://github.com/clojure-emacs/cider-nrepl/blob/711b47b20afc51b9a563358b4ad6c24ed1137269/src/cider/nrepl/middleware/info.clj#L172) is to first look at resource path before resorting to the Oracle official source. This allows the use a local copy of API doc, but only by either

• manipulating resource classpath (which is difficult to do in Emacs config) or
• putting a full version of API HTMLs under Leiningen's "resources" directory (which is specific to a single project).

It would be nice if we can specify a local doc path in Cider's Emacs config, to use a single shared copy of API doc, e.g., "/usr/share/doc/java/api" on a Linux machine.

I am not sure whether this can be configured now; I have not found a solution yet.

[pw4ever]

I have figured out an easier solution. I should have thought a bit more before posting the issue.

The solution is to simply add:

:dev {:resource-paths ["/usr/share/doc/java/api/"]}

to project.clj's :profiles. So a complete project.clj example is:

(defproject local.test "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.6.0"]]
  :main ^:skip-aot local.test
  :target-path "target/%s"
  :profiles {:uberjar {:aot :all}
             :dev {:resource-paths ["/usr/share/doc/java/api/"]}})

Alternatively, for user-wide configuration, use $HOME/.lein/profiles.clj

{:user
  {
    ;; local JDK API javadoc
    :resource-paths ["/usr/share/doc/java/api/"]
  }
}

A caveat: The hard-coding of local path loses the online fetching logic's ability to match the version of javadoc and the running JVM.

[bbatsov]

We might mention this in the read me.

On Sunday, December 28, 2014, Wei Peng notifications@github.com wrote:

I have figured out an easier solution. I should have thought a bit more
before posting the issue.

The solution is to simply add:

:dev {:resource-paths ["/usr/share/doc/java/api/"]}

to project.clj's :profiles. So a complete project.clj example is:

(defproject local.test "0.1.0-SNAPSHOT"
:description "FIXME: write description"
:url "http://example.com/FIXME"
:license {:name "Eclipse Public License"
:url "http://www.eclipse.org/legal/epl-v10.html"}
:dependencies [[org.clojure/clojure "1.6.0"]]
:main ^:skip-aot local.test
:target-path "target/%s"
:profiles {:uberjar {:aot :all}
:dev {:resource-paths ["/usr/share/doc/java/api/"]}})

—
Reply to this email directly or view it on GitHub
#930 (comment).

[pw4ever]

Good idea. There might be other people wanting to do the same thing, just not knowing how (like myself 20 minutes ago).

[pw4ever]

BTW A caveat should be mentioned is that the hard-coding of local path loses the online fetching logic's ability to match the version of javadoc and the running JVM.

[pgroce]

Is there a story about this for people who don't use Leiningen? It's not an itch I need to scratch, personally, but I like maintaining as much functionality as possible in my non-Leiningen-based (and admittedly weird) setup. (I use Gradle, but roll my own repl -- works fine with the middleware included. Some Boot users might have the same question.)

[pw4ever]

@pgroce The code in nREPL info middleware linked in the first post (https://github.com/clojure-emacs/cider-nrepl/blob/711b47b20afc51b9a563358b4ad6c24ed1137269/src/cider/nrepl/middleware/info.clj#L172) indicates that if you have the JDK API javadoc HTMLs that can be directly located with clojure.java.io/resource, that will be returned as URL to be displayed in browser.

In other words, for each non-Leiningen scenario, you only need to figure out how to include your local JDK javadoc path (e.g., /usr/share/doc/java/api in my case on Arch Linux) in your Java resource path.

The {:resource-paths ["/usr/share/doc/java/api/"]} code above does exactly that for Leiningen.

[pgroce]

Okay, that sounds perfectly straightforward. Thanks very much for the explanation.