Writing Grails Doc with GitHub

You're writing a Grails plugin and you would like to publish it to Grails Central. One important step is to wrtite documentation for it. Don't forget that gr8 doc will benefit your plugin.

Create Git Hub Pages

Using GitHub interface:

1. Go to Admin tab on your project, in the section GitHub Pages, click on the button Automatic Page Generator.

A markdown page will give a default template for your site, continue to layouts button.

2. Select a theme and publish. With the simplicity of GitHub, you're done. Site is online:

http://<gitaccount>.github.com/j<gitproject>/

GitHub has created a new branch: gh-pages.

Integrate with Grails Doc

 1. Switch to gh-pages branch

$ git checkout gh-pages

You'll notice all your folders present in master are gone, view is different

2. Create a grails app

3. Add doc structure following below example:

For the reference manual:
https://github.com/3musket33rs/html5-mobile-scaffolding/tree/gh-pages/src/docs/guide

Note the name of the file start with numbering and subnumbering

For the script:
https://github.com/3musket33rs/html5-mobile-scaffolding/tree/gh-pages/src/docs/ref/Scripts

4. Generate doc

grails doc

5. Copy links to github src from index.html + copy images from /resources to /img

6. Move generated doc (from target) to root

7. Open index.html and paste github src links

8. Switch back to master


$ git checkout master

As you can lot of manual step that could be package in a plugin...

 To come Soon

I shall write a plugin. Peter Ledbrooke started one a few years ago, it should worth packaging it.

Peter Ledbrooke blog on gh-pages and grails



Tweet