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:
$ gem install guides
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.ymlto add information about the new guide. Pay special attention to the
urlfield 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.