quick documentation for gems added to project

Hello,

I was wondering whether it is possible to setup quick documentation for the dependent gems of my rails project.  For example, if I am using "RMagick" in my rails project, what do I need to do (if it is possible at all) to make sure that I can see quick documentation for classes, methods, attributes from RMagick and also have code completion work for them as well.  Right now quick documentation and code completion works only for the core Ruby and Rails classes.  Am I missing somethign?

You should attach these gems to your project to enable code completion, quick documentation view etc.
You can do this in File | Settings | Ruby SDK and Gems | Attach gems action.

Regards,
Oleg

Oleg,

Thanks for quick reply.  But of course, I have already done this (attached dependent gems to my project in "Ruby SDK and Gems" configuration screen).  That is why I was surprized to see that RubyMine was not recognizing RMagick api and documentation.  Any other suggestions?  Thanks again,

Lev

Lev,

Could you provide some example, where you expect documentation from RMagic but it is missed.

Absolutely.

Here is a few lines of sample code with RMagick in a controller:

require 'RMagick'

imgl = Magick::ImageList.new
imgl.new_image 200, 200, Magick::HatchFill.new('white','lightcyan2')

gc = Magick::Draw.new

max_x = imgl.columns
max_y = imgl.rows

gc.affine(1, 0, 0, -1, 0, max_y)
gc.stroke('gray50')
gc.fill('gray50')
gc.stroke_width(1)

...

If I put a cursor inside any of this code (e.g. "stroke_width", "ImageList", "new_image", "rows" and etc.)
and go for a quick documentation lookup, I will get empty window doc window with "Documentation is not available"
(or something like that).  I also do not get any code completion on RMagick related stuff.

BTW,  I am running RubyMine 1.1 on Windows, RMagick version is 2.9.0.  Hope this helps...

Lev

Hello,
I'll try to install rmagic gem later today and check it. Probably RMagick is binary C extension and isn't written on Ruby so RubyMine isn't able to fetch documentation from ruby comments. Please look at gem source, do you see any ruby files with Magick ruby module and corresponding ruby classes?

Roman,

Thanks for investing your time to address this issue. I truly appreciate.  Let's get to the bottom of this

RMagick is based on a popular ImageMagick C library.   However,  it has ruby classes wrapped all around it with RDoc comments in them.  When you install the gem you can see the RDoc generated for it.  (and I can easily access it locally: one way would be running "gem server" and then going to "localhost:8808") but RubyMine for some reason does not pull it in.
Another mystery is why code completion does not work.  I would guess that code completion in RubyMine is not based on RDoc but rather on direct ruby code introspection.   Does it mean RubyMine does not see RMagick ruby sources at all?
I played much more with it last night - trying different things to force RubyMine to recognize RMagick but with no success.  Hopefully, you can get some anwers after installing it and checking out yourself.

Thanks,

Lev

Hello Lev,

I've tried it on my Mac and it works.

Obviously RubyMine doesn't understand some dynamic, e.g. ImageList use method_missing to redirect call to Image object. Also I don't understand (from RMagick 2.9.2 sources) where "columns" and "rows" methods are defined.

Please attach screenshot with similar code from your RubyMine.

I would guess that code completion in RubyMine is not based on RDoc but rather on direct ruby code introspection.   Does it mean RubyMine does not see RMagick ruby sources at all?

You are right our code analyze doesn't related to RDoc documentation. Please also attach screenshot of rmagic gem library which is shown in RubyMine. In my case it is

Roman,

I am posting a screenshot showing both:  1. RMagick is in my project libraries with sources recognized  and 2. Quick Documentation on the "affine" function is not working (exactly what you had success with in your test).  The main difference between yours and mine setup is Windows vs Mac OS.  Any chance you can verify this on a windows machine?

I've noticed that require 'RMagick' is highlighted with warning. I suppose "RMagick" gem still isn't attached to your project. Please check it again in Settings | Ruby SDK and Gem Manager

"RMagick" gem is attached to my project (has been attached since the beginning).  Here is my proof


Any other ideas?  This problem has been pretty elusive but I would really like to nail it.  My evaluation license is about to expire in a couple of days.  We were thinking about getting 3-4 licenses as overall I really like RubyMine (plus I am a 8 year veteran of heavy IDEA use in java development, has been a big fan from the begining).  But this issue became somewhat of stumbling block for me...    Code completion and quick documentation are 2 key productivity features for your products.  It is important to have them working properly.
I do appreciate you prompt responses trying to help me out with this...

Lev

Please attach idea.log file as described http://www.jetbrains.net/devnet/docs/DOC-1153

Any other ideas? 

A have no ideas right now. I've checked rmagick gem on MacOS and rmagic-win32 on Windows Vista and all works as expected. Which file system do use? Maybe it is case-sensitive problem.
Also try to create new SDK, new project with only rmagick gem attached and check autocompletion on your example.

Does the Quick Documentation feature rely on rdoc or ri files having been generated for the gem on the local machine? Or does it determine the necessary information itself from the source code? Some people turn off rdoc and ri generation when installing gems, by setting options in their .gemrc file, or simply by specifying them on the command line when installing the gem. Perhaps there is no rdoc available for RMagick gem.

Another possibility - is the RMagick gem installed in the normal system area, or is it installed in $HOME/.gem. This can happen if you forget to use sudo when installing the gem. Not sure if this matters to RubyMine, but would be interested to know what it does in this situation.

Does the Quick Documentation feature rely on rdoc or ri files having been generated for the gem on the local machine? Or does it determine the necessary information itself from the source code? Some people turn off rdoc and ri generation when installing gems, by setting options in their .gemrc file, or simply by specifying them on the command line when installing the gem. Perhaps there is no rdoc available for RMagick gem.

RubyMine's Quick Documentation feature doesn't rely on rdoc or ri files. RubyMine uses only source code and comments to show this info.

Another possibility - is the RMagick gem installed in the normal system area, or is it installed in $HOME/.gem. This can happen if you forget to use sudo when installing the gem. Not sure if this matters to RubyMine, but would be interested to know what it does in this situation.

I dont think this can cause such a problems, RubyMine works fine with gems installed without superuser privileges. Moreover it's default behavour for RubyMine Gem manager when installing gems.

Regards,
Oleg

Thanks for educating me, Oleg. Those behaviours both seem like good choices for the product - depend as little as possible on variations in the developer's environment.

Interesting that most Ruby developers seem to install their gems globally rather than just under their home directory. They are annoyed when they forget to use sudo, and a gem is accidentally installed in $HOME/.gemrc. Not sure why this is. It might even be preferable, in many cases, to limit the scope of gems to the current user.

Hello Paul,

Thanks for educating me, Oleg. Those behaviours both seem like good choices for the product - depend as little as possible on variations in the developer's environment.

We plan to implement external documentation feature for RubyMine http://www.jetbrains.net/jira/browse/RUBY-3309
Feel free to vote, comment and watch it to get notifications when it's complete.

Interesting that most Ruby developers seem to install their gems globally rather than just under their home directory. They are annoyed when they forget to use sudo, and a gem is accidentally installed in $HOME/.gemrc. Not sure why this is. It might even be preferable, in many cases, to limit the scope of gems to the current user.

I think now it's ok, because latest versions of gem support localy installed user gems as well as installed using superuser privileges, some time ago gem was unable to uninstall localy user installed gems without some special command line modifiers.
As for me, I prefer installing gems with sudo, but launching external processes with sudo from Java seems problematic.

Regards,
Oleg

This has to be something Windows specific since I just attached Shoulda and Factory Girl gems using the technique that you described and the Quick Docs show up without any problems.  However, there is something that I don't understand.  I had the gems already installed and wrote a large number of Shoulda test with Factory Girl using NetBeans (it already supports Shoulda and is really convenient to test in a single file environment).  Rubymine somehow could not figure out that I had the gems already installed and asked me if I wanted to install those gems?  I said yes, it ended up installing those gems (sqlite) gems that I had missing in my '/home/.gem' directory and recogized the Shoulda/Factory Girl gems that were previously installed
.
Think about it!  If you are installing Rubymine in your home directory as I have and run rubymine.sh in the bin directory as yourself rather than as root then the gems will have to go the the .gem directory since Gem manager does not have permissions to install as root (preferred as most users install their gems in the systems path).  Therefore, may I suggest that you prompt the user for their root password when attaching/installing missing gems? NetBeans has had this problem for a long time and I just install all the gems at the command line since it does not add any value (only confusion!) to your IDE experience.  I think you should separate these two activities.

Hope this helps.
Bharat

rather than as root then the gems will have to go the the .gem directory since Gem manager does not have permissions to install as root (preferred as most users install their gems in the systems path).  Therefore, may I suggest that you prompt the user for their root password when attaching/installing missing gems? NetBeans has had this problem for a long time and I just install all the gems at the command line since it does not add any value (only confusion!) to your IDE experience.  I think you should separate these two activities.

Why do you to want install gems not in .gem directory? Old versions of rubygems doesn't support 'locally installed gems' and in current version it is work ok.

However, there is something that I don't understand.  I had the gems already installed and wrote a large number of Shoulda test with Factory Girl using NetBeans (it already supports Shoulda and is really convenient to test in a single file environment).  Rubymine somehow could not figure out that I had the gems already installed and asked me if I wanted to install those gems?  I said yes, it ended up installing those gems (sqlite) gems that I had missing in my '/home/.gem' directory and recogized the Shoulda/Factory Girl gems that were previously installed

May be it was some bug in RubyMine. But I don't know how to reproduce it. Obviously RubyMine should see all gems that available with read permissions. By the way did you change gem paths manually? RubyMine caches gem's paths on SDK creation(see output of command: "gem environment paths") and refreshes them only after new gem installation. So if you create sdk, then add new gem path - RM will not see it. But if you install some other gem RM will refresh cached gem paths and will see your additional gems.

Sorry guys, I have been out of the loop for the past few days.  But the good news I got it working (for the most part).  Basically, I played with it a lot and ended up abandoning my current project, recreating it anew, reattaching gems and so forth.   And even though my new setup is no different from what I had before (at least, I do not see any differences), it is recognising RMagick gem now.  I do get some RDoc and auto-completion.  Though I can not say it is perfect (far from it). It does not pull quick documentation for classes and not for all methods/attributes either.  The same goes for autocompletion.  Yet it is much better than before   (I do not mean to complain - just trying to provide my input for the improvement of already great product like RubyMine).   Here is the example:

require 'RMagick'  #  No warning here, looks great now.

include Magick #  No warning here, looks great.

image = Magick::Image.new ....   #  No warning but not getting any doc on Image class.
gc = Magick::Draw.new #  No warning here but not getting any doc on Draw class.

gc.fill("blue")  # This one is great, both autocompletion and quick doc on "fill" works.

gc.annotate(image, 0, 0, 0, 0, "Some text") do  # No quick doc or auto-completion on "annotate".
     # This whole section is full of warnings with no autocompletion and quick doc working at all.
     # So everything (attributes ["fill", "gravity" and etc.] and constants ["NorthGravity", "ItalicStyle"]) are underlined as warnings because they are not recognized.
     self.fill = "green"
     self.font_size = 12.0
     self.gravity = NorthGravity
     self.style = ItalicStyle
end

By the way, if I do not use "include" above and explicitly prefix every class and constant with "Magick::" it does not make any difference.

image = Magick::Image.new ....   #  No warning but not getting any doc on Image class.

RM show doc according to comments in code. In this case authors of RMagic were a bit lazy with comment. If your open Image class you will see

# Ruby-level Magick::Image methods class Image
....

and RM show the same documentation. We will add rdoc support in future =), please vote for http://www.jetbrains.net/jira/browse/RUBY-3309

gc.annotate(image, 0, 0, 0, 0, "Some text") do  # No quick doc or auto-completion on "annotate".

does it work? I see annotate method for Image class but not for 'Draw'. Also I don't see where in RMagick source 'annotate' method may be defined for 'Draw' class. Also Draw doesn't extends from Image class.

gc.annotate(image, 0, 0, 0, 0, "Some text") do  # No quick doc or auto-completion on "annotate".
     # This whole section is full of warnings with no autocompletion and quick doc working at all.
     # So everything (attributes ["fill", "gravity" and etc.] and constants ["NorthGravity", "ItalicStyle"]) are underlined as warnings because they are not recognized.
     self.fill = "green"
     self.font_size = 12.0
     self.gravity = NorthGravity
     self.style = ItalicStyle
end

I think it is some RMagick dynamically defined magic and annotate's closure (block) will be executed in context of some other object instead of context from pure ruby point of view.
We are working on ruby API for RM which will allow users to extend our type inference engine and promt RubyMine about types of some methods calls, some dynamically defined methods, etc.

Thank you for examples =)

Roman,

Thanks for the explanation - duly noted.

As far as "annotate" method, yes - it works and it is there.  It is an instance method  of the "Draw" class and it has a whole bunch of its own attributes like "fill=", "gravity=" and so forth which are used in annotate's closure.  Please see:

http://www.imagemagick.org/RMagick/doc/draw.html#annotate

I just though it was interesting that "fill()" primitive method is recognized, but "fill=" attribute (for "annotate") is not.   Possibly a bug?  (autocompletion should have picked up even if documentation/comments are missing in the code, right?)

On the other hand, I totally understand your point regarding abscence of comments (on the class level) for Draw and/or Image classes. Thanks.

Lev

Lev,

I just though it was interesting that "fill()" primitive method is recognized, but "fill=" attribute (for "annotate") is not.   Possibly a bug?

RM found "fill()" method declaration in  RMagic::Draw class. As for "fill=" it is attribute accessor which is defined somewhere but RM (and me too) cannot find it's declaration in RMagic sources. Probably it's defined somewhere in C extension. And are you able to find this declaration in rmagick sources =) ?

(autocompletion should have picked up even if documentation/comments are missing in the code, right?)

Yes and RM doesn't use comments for autocompletion - only code analyzes. But actually sometimes it's impossible  to infer type of something due to ruby's dynamic nature and lack of static type inference in ruby. So full autocompletion in all cases is impossible without code execution. In such cases we can only allow users to prompt about types of some objects. We also plan to support optional type annotations in future.