Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Build your own Rails guides

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 Gemfile
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 guides.gemspec
README.md

guides

This gem provides a clean a simple way to generate and maintain a collection guides or how-to documents for your project.

guides is inspired in the Ruby on Rails Guides site (http://guides.rubyonrails.org). Some of the documentation sites that have been built using guides include:

Installation

$ gem install guides

Usage

First create a new working directory.

$ cd /tmp/
$ guides new projectguides
$ cd projectguides/
$ guides preview

Then open a browser and point it to http://localhost:9292. You will see your new documentation site up and running.

From this point on, it is up to you to customize the site and add additional guides.

Once you are happy with the results, you can generate the final site by running:

$ guides build

Adding a new guide

There are two steps required to add a new guide:

  • First you need to edit guides.yml to add information about the new guide. Pay special attention to the url field you choose.
  • Then you need to provide the guide's contents by creating a new file under ./source/.textile

Guide authors and contributors

As you will see, the guides.yml file also contains a section that lets you define guide authors and contributors. The contents of this section will be rendered to the Credits page (http://localhost:9292/credits.html).

You can include an image field to provide an avatar for each of the contributors. For example:

authors:
  Documentation Team:
    - name: John Doe
      nick: johndoe
      image: credits/johndoe.png
      description: Brief bio of J.D.

As long as you place your avatar files under ./assets/images/credits/, guides will find it and display it in the Credits page.

Contributing to guides

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so we can cherry-pick around it.
Something went wrong with that request. Please try again.