If I want see documentation on my gems I can do:
yard server --gems
How can I see the documentation of Ruby's standard library?
You have to
download the Ruby code archive and extract it into a directory,
run yardoc *.c (that will generate the core documentation),
2a. run yardoc . (that will generate the stdlib documentation but will take a lot of time),
run yard server.
(from http://gnuu.org/2010/10/13/local-copies-of-documentation/)
Related
I'd like to develop some reusable step definitions and scenario outlines for Cucumber in Ruby.
I've scoured the Cucumber wiki but there seems to be no info on use of Cucumber with Ruby gems.
Is there support for execution of a feature from an installed Gem?
Or would a user have to manually change to the gem installation directory and explicitly referenced the feature(s) to run from there?
If I understood your question correctly, all you need is to create some lib for reusable definitions and steps, and then require this lib(or gem) in features/support/env.rb
Here is a gem does exactly the same as you need, you can use it as a reference: https://github.com/jayzes/cucumber-api-steps
Look at the features this gem provide: https://github.com/jayzes/cucumber-api-steps/blob/master/features/request.feature The gem created some reusable parts.
Turns out cucumber --help shows the way:
cucumber -r gem-name feature-name.feature
UPDATE: This doesn't work. Any other suggestions?
There is a cucumber gem which installs the binary cucumber.
Running this command, will assume default settings. This means it will look under ./features relative to the current path for files with the .feature extension. It will expect ./features/step_definitions to hold files with *_step.rb, where it will search for steps.
Edit: never mind, I misread your question and thought you wanted to know about the cucumber gem and its default paths.
When I pass CSV to ri I get this output
Nothing known about CSV
I thought all ruby classes are documented with ri.
CSV is a part of standard library and is fully documented. That issue may be linked wit rvm using. Try to prepare rvm docs generate command.
If RI returns "NOTHING KNOWN ABOUT..." the documentation may be missing.
RI documentation isn't included when Ruby is installed.
It must be manually generated - ideally, immediately after installing EACH VERSION of Ruby (before the downloaded installation files are cleaned up).
To generate it:
$ rvm docs generate
If that doesn't work, check this RVM.io page for command options & scenarios.
With Jeweler I created a gem folder structure with ease.
However, I still have some questions:
Why are params like --gemcutter and --rubyforge still available for Jeweler. Aren't these replaced by RubyGems? Do I have to specify anything to create a gem for RubyGems?
In the Rakefile I have information about the gem, and when I run "rake install" it created a gemspec. Why is the same information in two places?
What is a manifest? Just read about it, haven't seen such file.
How do I make my gem callable from the shell once I have installed it, like rails. Cause right now it's just accessible through a Ruby script using require.
Should I use "jeweler release" or "gem push" to push my gem to RubyGems.org?
I have to specify "handle" when signing up in RubyGems. What is that?
Thanks.
jeweler was created before RubyGems became what it is, so it still reflects the split. I'm not sure when jeweler was last updated, either. (I think it also still recognizes building gems on Github, which is now disabled.)
I'm not sure I follow what you're saying. The specification in the Rakefile details what the spec that gets written should look like. The spec that gets written details what should be installed and how, I believe.
A manifest is a list of all the files that your gem should ship with. Not everyone uses one. See the hoe documentation for some pro-manifest discussion.
Many Ruby gems are only libraries. If you want yours to also have a program like jeweler or rake or rails that you can call, you have to write the callable program, put it in bin in your gem's layout and specify (in your gemspec) that it should be packaged and installed. See the Gem::Specification reference under files and executable.
Not sure. Consult both jeweler's docs and the docs for RubyGems.
You can give an email address or use a name (a 'handle', like I use Telemachus here), which is all they mean by 'handle'.
For the record, if you are just learning how to write gems, you do not need to upload your first attempts using RubyGems or anything like it. You can simply install the gem on your machine only.
Has much changed with the release of Bundler? Is there a template that can be used as a base? What are the best practices?
Some posts that I have found useful:
http://chneukirchen.github.com/rps/
http://tomayko.com/writings/require-rubygems-antipattern
http://yehudakatz.com/2009/07/24/rubygems-good-practice/
http://weblog.rubyonrails.org/2009/9/1/gem-packaging-best-practices
Edit (2012-01-10): An excellent all-around guide to gem best practices is RubyGems Guides. I would highly recommend starting here now.
To summarize the key points:
Use the basic lib/gem.rb and lib/gem/ structure for code.
Put any executables in bin, any data files in data and tests in test or spec.
Don't require or depend upon files outside of the load path. (VERSION files often seem to live in odd places in gems.)
Do not require 'rubygems'.
Do not tamper with the $LOAD_PATH.
If you find yourself writing require File.join(__FILE__, 'foo', 'bar'), you're doing it wrong.
The simplest way it's to use bundler:
bundle gem <gem_name>
You may even use it in an existing project from the parent directory.
When writing fat (binary) gems the structure is usually this:
lib/1.8/binary.so
lib/1.9/binary.so
lib/my_gem.rb (this file simply chooses which binary.so to load depending on ruby version)
And for native extensions:
lib/ext/my_gem/my_sources.*
lib/my_gem.rb
I also usually put a version.rb file here:
lib/my_gem/version.rb
and it simply contains something like:
module MyGem
VERSION = "0.1.0"
end
Also, IMO, don't put any .rb files except the file you want people to use to load the gem, in the lib/ directory. Instead put all auxiliary files in lib/my_gem/
This rubygems guide provides information about the structure of a gem and then goes into detail about what should be included in your gemspec
You may find it easier to use bundler to create the folder structure of the gem for you:
bundle gem <gem_name>
my_gem$ bundle gem my_gem
create my_gem/Gemfile
create my_gem/Rakefile
create my_gem/LICENSE.txt
create my_gem/README.md
create my_gem/.gitignore
create my_gem/my_gem.gemspec
create my_gem/lib/my_gem.rb
create my_gem/lib/my_gem/version.rb
Initializing git repo in /Users/keith/projects/my_gem/my_gem
Telemachus's advice is good. If you follow it your gem will be setup to play nicely with bundler.
You might also try using jeweler. It's a gem that generates skeletons for gems. The default skeleton that it spits out complies with all of the conventions Telemachus mentioned and it will also do some nice things like add your favorite test framework or create a GitHub repository.
In Ioke doc, the ISpec tests are included in the documentation, see ioke.org/dok/index.html
How can this be done with Ruby's RSpec and RDoc (or SDoc)? I can't find any commandline switches or external libs to do so. Any ideas (not including implementing it all by myself ;-) )?
Time helps: Now there's a plugin for YARD doing exactly what I want: http://github.com/lsegal/yard-spec-plugin