A cheatsheet to generate documentation for your rails project on GH Pages

I looked around for an article on how to generate documentation for a rails project in GitHub pages and couldn’t find anything recent, so I decided to publish a short guide here.

If you have any questions or you get stuck, feel free to comment below and I’ll do my best to help.

1. Install the ‘yard’ gem

Go to your repository’s Gemfile and add the following line at the bottom:

gem ‘yard’

Then run the following command in your terminal:

$ bundle install

Yard has decent documentation available here: https://yardoc.org/ that you can use if you want to customize which files it generates documentation from.

2. Generate docs

Run the following in your Terminal:

$ yard -o docs

Why? You’re adding “-o docs” to change the directory from the default (/doc) to (/docs), which is necessary for GH-pages

3. Push to Github

git add .
git commit -m "updating docs"
git push origin master

4. Launch to GH-pages

• Go to your repo (i.e. https://github.com/USERNAME/REPOSITORYNAME/settings
• scroll down to Github pages > click on the “Source” dropdown > select the second option `master branch /docs folder`

5. Celebrate!

That’s it! Your documentation should be available at http://yourdomain.com/repo-name

Whenever you want to update your docs, follow steps 2) through 5) above.

If you have any questions or you get stuck, feel free to comment below and I’ll do my best to help.