Skip to content
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
Closed

specify local path for API javadoc #930

pw4ever opened this issue Dec 28, 2014 · 7 comments

Comments

@pw4ever
Copy link
Contributor

@pw4ever 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
Copy link
Contributor Author

@pw4ever 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
Copy link
Member

@bbatsov 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
Copy link
Contributor Author

@pw4ever 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
Copy link
Contributor Author

@pw4ever 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
Copy link

@pgroce 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
Copy link
Contributor Author

@pw4ever 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
Copy link

@pgroce 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
…c over the online version on Oracle's site
@bbatsov bbatsov closed this in ef645cf Jan 7, 2015
bbatsov added a commit that referenced this issue Jan 7, 2015
[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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
You can’t perform that action at this time.