I'm working on a web site which provides API for external developers.
Whenever the API is updated (i.e. modified parameters, new end points, etc), I have to update the documentation manually.
So I'm looking at how this process can be be done automatically. Here is what I hope to acheive: once my source code is updated and committed to my source control, some sort of an API Registry will be updated. So my documentation can be an app which refers to the registry and shows the viewers with the latest API.
My site is based on Ruby on Rails.
RDoc is automatically generated based on your source code, and it comes default with Rails. Your code needs to be well-documented, but if it is, you can just run
bundle exec rake doc:app
and your app will generate documentation accessible from doc/app/index.html. I would look at that and see if such documentation fits your needs. Links in the "Class and Module Index" sidebar contain lists of all of your methods with expandable views of the source code for them.
I use a custom rake task that places all of that documentation in the Rails public folder for access directly from my website and allows me to add more than one custom page. I imagine it wouldn't be that hard for you to do something similar that only parsed your API files.
Links:
RDoc Syntax Help
Project on Github
Related
I am creating a rails web app that is a really a content management system. Thus there is going to be a admin section of the app. There I want users to be able to set config setting that are available through the app. Thus I want basic CRUD functionality for config settings. (If you've ever used the admin section of the Discourse discussion board, you'll know what I want to do)
Most of the config gems I have seem to be about organizing config info during development, but seem to expect that config info to be basically set and static on production. (See How to define custom configuration variables in rails)
However, in the above link there was one gem called rails-settings (https://github.com/Squeegy/rails-settings) that, in its description, seemed very close to what I want. However, it seems very old (last commit was 2009).
Three related questions:
1) Is there is a standard Gem for this kind of thing that I'm missing?
2) Should I use rails-settings?
3) Should I just create my own model called Settings < ActiveRecord and would this model be available throughout all my controllers?
Before I start the process of building something from scratch I was curious if anyone else had come across a way of providing a first-time configuration wizard for a Rails application that allows the user (sysadmin) to configure aspects of the application such as the ActiveRecord configuration and the ActionMailer setup (SMTP, sender etc).
We'd like to provide a clean easy way for new installs to get setup, rather than asking clients to edit files, or run scripts on the command line.
Essentially you should be able to download the application, extract it, start it, and when you access it via the browser you're guided through the initial setup steps.
My question isn't so much around how to do this, but more has anyone already done this. My quick search for gems, plugins etc around this idea didn't turn up much.
Edit/Clarification
To clarify the scenario - this is to support "shrink-wrapped" products that are downloaded and installed on-premises by the customer's sys admin.
The first time they access our application after deploying it behind their firewall we want a friendly way of configuring the specific settings for their install, such as database etc.
An example of such a process is JIRA's setup wizard:
https://confluence.atlassian.com/display/JIRA/Running+the+Setup+Wizard
This isn't for reating new rails applications, or systemising our development process.
I like Rails Templater a lot. It is a command line tool to build a rails app. It asks you questions like "Would you like to use rspec? Pry instead of IRB?"
I have created a fork that adds authentication, twitter bootstrap and backbone.js and some other options. It is pretty easy to hack on if you have specific needs. I use it all the time and I would hate not having it.
It is of course a command line app and not usable via the browser but maybe it will still fit your needs. Or the codebase could be integrated into a client web application.
Update after comment
You may be able to bootstrap a sqlite database so the app can boot, then just using a form or a wizard to set up something that writes your database.yml and other configs, maybe by means of thor (makes appending/replacing text in files simple and is part of rails). You would need to somehow restart the rails app and migrate the database. You could keep the pg or mysql2 gem (or both) in your Gemfile or again use thor to edit them from your wizard/form.
I also recommend using rails_config as Michael suggested. With the above solution.
If I had more time to think about the problem, I may come up with something cleaner but this is how I would do it if I had to right now.
http://railswizard.org/ lets you select which gems to use. It's a very innovative use of the ui and the isotope gem to select the components. Similarly another viewpoint is this top 10 list: http://blog.teamtreehouse.com/10-must-have-ruby-gems
You'll never find a definitive list of gems as need change from person to person and over time, e.g. which database your company uses and which is the 'current' best authentication gem are both variable.
For configuration specific settings you can make the configuration less of a chore by using practices that reduce it. For example the database.yml file is usually one of the 'must be edited locally' files. Our approach for this to to exclude database.yml from source control by putting its name in our .gitignore file. We add an database.yml.example file which we copy locally to database.yml and in that file we use anchors (&) and references (*) as detailed here: http://blog.geekdaily.org/2010/08/advanced-yaml-tricking-out-your-databaseyml.html
More options for configuring other variables for each environment: http://kpumuk.info/ruby-on-rails/flexible-application-configuration-in-ruby-on-rails/
The rails config gem may also help you as detailed here: How to define custom configuration variables in rails
A few months ago there was a feature in the Rails API documentation that let you visit the a Rails source file on Github by clicking "on Github". Ryan Bates even tweeted about it. This was a great feature because you could easily explore the source for the entire file instead of just for a single method.
Does anyone know what happened to this feature?
I believe they removed them when they started using Ajax for the show. This happened when they switched to sdoc. Perhaps its an sdoc limitation, as everyone seemed to enjoy it.
I would recommend posting on the google group and get a discussion going requesting more information and/or getting them back.
You can find the group here.
Rails documentation generated from using the standard Rdoc Rake task provided with the rails source still produces this extra link to github.
There's still a flag for it in the rakefile.
Whatever or whoever generates the documentation for the API must be omitting this flag.
It looks like the github links are back as of Rails 3.2.0!
I want to get into rails by examining well built code
where can i find typical open source rails project that i can download
and learn from ?
i'm interested in facebook connect integration (facebooker), tag clouds, searching in
my website
I'm not looking not tutorials or screen casts
Thanks!
This question gives a good list
a list of projects with good test-suites
a list of open source rails apps to learn from
Have a browse of ruby tool box and download some open source. For example there's refinery and zena, two content management systems and Rboard, a forum. Depends what you want really but there's plenty out there. Ruby toolbox entries are ordered by github watchers and forks to give you an idea of their popularity.
I really like looking at the commits in teambox.
I find it a bit more complicated. But there's also spree.
There's also devise which is really interesting to look at too.
Finally, I'd recommend you to follow the rails commits (it's the only commits feed I have in my Google Reader).
Gady, this is an extremely rich topic you're asking about and resources are all over the internet. Try starting at http://rubyonrails.org/.
You should be able to find tens of questions just like yours (asked and answered) by searching SO at the top bar.
For Rails, part of it is the building process, so one feasible approach is to read a tutorial like http://railstutorial.org/book
then when in Chapter 2, you will use Scaffold, and at that time, you will have some basic code to look into how a basic Rails app is.
I also suggest you use source control like Git, Mercurial, or SVN to commit different phases of the project, from creating the rails project and then after each step, so you can diff what the changes are during each step.
If you already have Ruby 1.9.2, Rails 3.0.1, and sqlite3, then you can
rails new myproj
cd myproj
rails generate scaffold foo name:string salary:integer gpa:float note:text
rake db:migrate
rails server
and now you can use http://localhost:3000/foos to create, display, update, delete the foo records, and have quite a bit of source code to look at. Most of the customizable code is in app, with css and javascript in the public folder.
Ryan Bates has an excellent series of videos.
http://railscasts.com/
An extremely valuable resource.
Radiant is a CMS that you can download for free and see how it works. It is a great piece of code to look at and see how it works.
I guess that most open source Rails projects are shared on Github, so it may be interesting to browse its Ruby section and look for most watched or most forked projects:
http://github.com/languages/Ruby
Steady stream of new interesting projects to take a look at :)
And don't forget the official:
guides.rubyonrails.org
well there is one "bigger" project on github, waiting for downloading and contribution...
but it's a little controversial because of the security issued they have (had?)
It's still worth a look:
http://github.com/diaspora/diaspora
I'm starting research on what I'd need in order to build a user-level plugin system (like Wordpress plugins) for a Rails app, so I'd appreciate some general pointers/advice. By user-level plugin I mean a package a user can extract into a folder and have it show up on an admin interface, allowing them to add some extra configuration and then activate it.
What is the best way to go about doing this? Is there any other opensource project that does this already? What does Rails itself already offer for programmer-level plugins that could be leveraged? Any Rails plugins that could help me with this?
A plugin would have to be able to:
run its own migrations (with this? it's undocumented)
have access to my models (plugins already do)
have entry points for adding content to views (can be done with content_for and yield)
replace entire views or partials (how?)
provide its own admin and user-facing views (how?)
create its own routes (or maybe just announce its presence and let me create the routes for it, to avoid plugins stepping on each other's toes)
Anything else I'm missing?
Also, is there a way to limit which tables/actions the plugin has access to concerning migrations and models, and also limit their access to routes (maybe letting them include, but not remove routes)?
P.S.: I'll try to keep this updated, compiling stuff I figure out and relevant answers so as to have a sort of guide for others.
You might want to check out mephisto, it's a blogging software built with ruby on rails and has add-on plugin support. Not sure if it works how you are thinking of, but might give you some good insights. The source can be found on GitHub.
You should look at deface gem. It allows to customize rails views, adding content via hooks and replacing whole views/partials. Spree is using this gem so you can look also at spree. Beside views they also have other solutions for customizing application so you can find more answers to your questions.