I'm trying to prettify my rdoc documentation, using version 3.5.3. I'm not a fan of the built-in darkfish theme, so I tried to find a way to replace it with the one used by the official Rails API documentation at http://api.rubyonrails.org/, but I've had no luck finding it in any readily available form. I've searched all over github, among other things.
What I've found so far is
https://github.com/mislav/hanna
which might be slightly out of date, and it's fork
https://github.com/rdoc/hanna-nouveau
Both are nice, but not quite what I want. So before I start fiddling with those templates, does anyone know if the template used by the Rails API docs is available as a gem somewhere?
Thanks!
I know this is very late, but it looks like the new version of Rails uses something called sdoc, which enhances the output with JavaScript searching, and is a little cleaner IMO. Doing a simple "gem install sdoc" will get what you need, then just use rdoc.options << '-f' << 'sdoc'.
The github project appears to be at https://github.com/voloko/sdoc/
By the way, thanks for the question! Without the initial answer posted, I'd have never found where to look, and been stuck with that horrible darkfish theme for my own projects!
This looks like it. Ignore the instructions that say to do a gem install horo --pre -- that'll actually give you an older beta version. Just do gem install horo and you'll get the current 1.0.3 version (Edit: I sent a pull request to update the instructions, which has already been accepted).
https://github.com/tenderlove/horo
By the way, I found this by looking at the Rails source code and viewing the Rakefile to see the RDoc options. Specifically, line 67 shows rdoc.options << '-f' << 'horo'.
Related
My question is about the ruby-doc.org documentation, but also relates to the ri documentation lookup inside ruby.
I've already read dozens of similar questions/answers about the ri not working and giving "nothing known" messages and I've tried to follow some of that old advice. It just seems that those old answers aren't applicable to me.
One was to install the rdoc --all --ri from the ruby root directory. I tried that and it failed (unable to convert to UTF8 or something like that).
Another suggested that the rubyinstaller for windows installer just doesn't contain that info anymore and I should use the online documentation, which, when I goto http://ruby-doc.org/downloads/ I discover that the version I am using (2.4.4) does not exist.
This is odd, because the rubyinstaller site specifically says that if I'm new to Ruby(which I am), I should install 2.4.4. You'd think that if any version had good documentation, it would be that one. Instead, it seems to be missing entirely.
This all started because I am trying to learn Ruby and am watching the Lynda.com course on Ruby by Kevin Skoglund, which was recorded many versions ago and in that course he refers to the ri command from the shell, which in my version doesn't work. see below:
ruby --version
ruby 2.4.4p296 (2018-03-28 revision 63013) [x64-mingw32]
ri --version
ri.cmd 5.0.0
ri String
Nothing known about String
Now, if it's not available within ruby using ri, and I have to use online documentation, AND it's missing for my version, which happens to be the version recommended for new users, … you see my frustration.
Here's what I really want...
1. I want to use ri and have it work.
2. If that's just not possible, I'd like to know where the documentation for my version is online, because it's not where it's supposed to be.
Any help is appreciated. If it involves installing anything, letting me know HOW to do that is also appreciated. As I mentioned, I'm new.
Since you are using the RubyInstaller, I will assume that you are on Windows.
I will open this by saying that I am not 100% on this, but I am pretty condfident in this answer.
The "Use 2.4, not 2.5" was due to errors with Ruby Gem when Ruby 2.5
was first released, as I happen to be on a Windows machine installing
Ruby at that exact time, and that was the reasoning at that point not
to use the newest 2.5 version.
The above mentioned reason has since been corrected.
Realistically, if you are beginner, as long as you using documentation that is close to your version (2.0+ - 2.4-ish), it will be fine. Now obviously, and I shouldn't have to provide this disclaimer, though I will so to avoid the inevitable down-votes if I don't, this is not 100% perfect solution and there will be very small differences. As a beginner, the likelihood of you encountering any of these differences are extremely low, low enough not to even worry about. There are missing and poorly documented sections of every language, and Ruby is no exception. Typically these are less used classes (though Ruby Fiddle is an exception that I hate how poorly documented it is), and will have no effect on your learning process as you learn the fundamentals and core of the language.
To my recollection, the "core" is rather well documented, and so long as you use documentation from 2.0+ (the closer to 2.4 the better), you should be completely fine, and it is exactly the same. The "standard library" may be slightly more hit or miss, and your mileage may vary a little more, yet still nothing too extreme.
So, to address the second part of your question, do not worry too hard about finding the EXACT version of documentation you are using. It may not even exist online, though the installer should have provided a CHM help file (there will be shortcut for it with the shortcuts for Ruby, IRB, etc.
As for "why" ri is not working, I am not 100% sure yet again. I am on ArchLinux, and RDoc doesn't even built. Honestly, RDoc is being left by the wayside for newer (and IMO better) document engine, namely YARD. A possible solution that I do, and prefer, is to install the YARD gem right after I install Ruby:
gem install yard
And then set YARD to generate my documentation with this in CMD:
yard config --gem-install-yri
If you decide to take this route, much more can be learned about it here.
The benefit with it is that it also supports RDoc and is backwards compatible.
I'm really just a beginner to ruby, so hopefully this is an easy one. I've got to the point where I'm starting to look into some of the gems that the community have put together. I decided to check out something that would help my application consume rss feeds. So, headed over to rubygems (which is where i thought people go to get these kinds of things) and searched for rss. I found this one;
http://rubygems.org/gems/simple-rss
instructions were to just install the gem with
gem install simple-rss
So far, so good. When i came to actually use the gem, the documentation I received from doing the above was a bit naff, so i searched a bit further and found the git repo;
https://github.com/cardmagic/simple-rss
The documentation there (their code examples) complain about missing methods etc. and after a bit of digging I came to the conclusion that I must have downloaded an older version of the gem than the git trunk.
So, my question is, should I be using rubygems to get the latest gems, and if not, what other resources are out there to help find the latest builds of the comminities gems?
As far as finding a good gem for a task — use Ruby Toolbox, since it also shows you how actively maintained a gem is. Here's, for example, a section on feed parsing.
If you want to get the latest gem code that hasn't been released yet, you could download the code directly from github and build the gem yourself. However, it's easier to use bundler for that. It allows you to create a Gemfile for your project looking something like the following.
gem 'simple_rss', :git => "git://github.com/cardmagic/simple-rss.git"
Then run bundle command to download and build these gems from their corresponding sources.
In general, bundler is a great solution for managing gem dependencies for any ruby project. It provides ways to quickly reference any released gems, automatically builds gems directly from a git source, git refs, or paths on your filesystem, and has other convenient features.
By far the best place for all things Ruby & Ruby on Rails for the devs is the Ruby Toolbox
Hey, seems to be a few questions on SO about making a ruby gem. I'm interested in those of you that have actually built gems, hoping for Rails3, and your experiences with resources that you have used to make a gem.
My question is the title: Which resource did you find to be the most helpful when making a gem?
Jeweler is an awesome tool that does most of the packaging / gem layout work for you. I've used it in every gem I've made.
I found that intro quite useful to get started:
http://buzaz.com/index.php/2010/01/03/how-to-build-a-ruby-gem/
You could also have a look at this Railscast:
http://railscasts.com/episodes/135-making-a-gem
I've looked in a lot of places - including www.rubygems.org - but can't find any tutorial that describes an easy, straightforward, technique for producing gems that doesn't rely on other (non-standard-Ruby) components, such as newgem and hoe.
I have several requirements for gem production, from the simplest case of one library file+one test file, to complex ones involving C source files and multiple utility .rb files.
All help gratefully received!
I was researching gem making recently and was also surprised that there wasn't a single, obvious way that everyone does it like how RubyGems is the one-stop shop for managing gems. I discovered that you can actually use Bundler to create gems, and I've chosen this route for my own gems. Take a look at this guide on gem development with Bundler by Radar.
look into Jeweler or one of these options:
http://ruby-toolbox.com/categories/gem_creation.html
its seems like overkill, but you don't need to use all the options, you can use it just to create the skeleton of the gem.
I've recently been looking into the same thing. Here are a few sources I found useful Walk through of a simple gem, Gem spec reference. Also I found it useful to check out large projects on github and model after them Thor's Gem spec.
Don't know if you've seen "Gemcutter Is The New Official Default RubyGem Host", but it's a good starting point. RubyGems.org is a good second stop to read Creating Your Own Gem.
The Ruby (and RoR) community publishes a large number of gems. But more often than not using these gems requires a good amount of effort, specially if one is new to Ruby. It would to be nice if Ruby experts (rockstars) share the best approaches to utilize inadequately documented gems.
Thanks
--arsh
As my manager likes to say:
The truth is in the code.
Look for examples of how others have used it, and modify as necessary.
There are frequently example directories in gems
Search the internet, people like to put this stuff in blogs
Read the docs.
Maybe posted on github
Frequently a link from the rubygems page
If installed as a gem, you can host your own server with $ gem server then go to localhost:8808 to get a list of all your installed gems, and you click the one you are interested in to see its documentation.
Look for tutorials that cover the gem
Railscasts are great for this
Many gems will have a wiki on github
Many of the more useful / cool / fun gems will be talked about in different books. You can get a lot of tutorials about how to deal with a given gem by getting a book that uses that gem to do something. The downside of this is that these kinds of books tend to go out of date pretty quickly.
Look at the code
If the code base is small, or you have a specific question about how something works, or want the truly definitive source, go check out the code.
If the code is installed as a gem, you can type $ gem environment and it will tell you your rubygems dir. Go there, cd into the gem you are interested in, check out its code in the lib directory.
Ask a mailing list
If a gem or project is large enough, it will have its own mailing list. You can usually find these by going to its homepage or reading its readme.
If not, try asking about the gem on the Ruby or the Ruby on Rails mailing lists.
You can always give your own gems a rockstar promotion. Vimeo: Zombie-chaser version 0.1: Mutation testing ... with zombies!