Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge pull request #13 from etdsoft/add_readme

Provide some basic documentation
  • Loading branch information...
commit 283987cf2289eefa35c07491369a52aaedf913c4 2 parents e6e3101 + c0da7e4
@wagenet wagenet authored
Showing with 80 additions and 0 deletions.
  1. +80 −0 README.md
View
80 README.md
@@ -0,0 +1,80 @@
+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:
+
+* http://guides.sproutcore.com/
+* http://guides.dradisframework.org/
+
+
+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/<url>.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.
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.