New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

specify local path for API javadoc #930

Closed
pw4ever opened this Issue Dec 28, 2014 · 7 comments

Comments

Projects
None yet
3 participants
@pw4ever
Contributor

pw4ever commented Dec 28, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pw4ever

pw4ever Dec 28, 2014

Contributor

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.

Contributor

pw4ever commented Dec 28, 2014

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

This comment has been minimized.

Show comment
Hide comment
@bbatsov

bbatsov Dec 28, 2014

Member

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).

Member

bbatsov commented Dec 28, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pw4ever

pw4ever Dec 28, 2014

Contributor

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

Contributor

pw4ever commented Dec 28, 2014

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

@pw4ever

This comment has been minimized.

Show comment
Hide comment
@pw4ever

pw4ever Dec 28, 2014

Contributor

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.

Contributor

pw4ever commented Dec 28, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pgroce

pgroce Dec 28, 2014

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.)

pgroce commented Dec 28, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pw4ever

pw4ever Dec 29, 2014

Contributor

@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.

Contributor

pw4ever commented Dec 29, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@pgroce

pgroce Dec 29, 2014

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

pgroce commented Dec 29, 2014

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

pw4ever added a commit to pw4ever/cider that referenced this issue Dec 29, 2014

@bbatsov bbatsov closed this in ef645cf Jan 7, 2015

bbatsov added a commit that referenced this issue Jan 7, 2015

Merge pull request #932 from pw4ever/issue930
[Fix #930] Explain in README how to use local JVM API doc over the online version on Oracle's site
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment