GitHub Pages: publish your Grails plugin docs

Currently, the primary site for Grails plugin documentation is the plugin portal on the Grails web site. The trouble with the portal is that it doesn’t readily support multi-page documentation. On top of that, you can use gdoc to write a user guide for your plugin, but where will the generated manual go?

Thanks to Luke Daley, I discovered GitHub Pages as a potential solution for those plugins I have hosted on GitHub. This feature allows you to create simple websites on a per-project basis.

Getting started

Before you can start publishing websites to GitHub, you first have to create a ‘personal’ page. The process is straightforward: create a new GitHub repository, clone it locally, add an index page, and then push your additions to GitHub.

For example, let’s say your GitHub username is ‘franklin’. First, create a new GitHub repository with the name franklin.github.com. This repository will store your personal website. Once that’s ready, clone it and add an index page:

$ git clone git@github.com:franklin/franklin.github.com.git franklin.github.com
$ cd franklin.github.com
$ touch index.html
$ git add .
$ git push origin master

After the above steps, you will have a blank home page for http://franklin.github.com/. Note that it can take a while for your GitHub Pages site to activate. Also, you can access the URL http://<username>.github.com/ before you perform the above steps and you will see some instructions for setting up the various pages.

Now that you have a personal Pages site, you can create project sites with URLs of the form http://<username>.github.com/<projectname>/. The process for this is trickier, so I refer you to the instructions on the GitHub Pages. You can either do it via your local git, or you can got to the project page on GitHub, click on the “admin” button, and select the “Generate project page” link. I prefer the latter approach because it’s easier and involves less typing!

Once you complete the steps from either set of instructions, you will end up with an extra local tracking branch called ‘gh-pages’. This branch contains the website for your project and it’s where we will be storing the plugin documentation.

The plugin documentation

When the grails doc command first appeared, it allowed you to automatically generate API documentation for your projects. With Grails 1.2, its scope was expanded and it can now generate a manual that looks and feels just like the Grails user guide. You don’t have to do anything to get the API documentation, but the manual requires a bit of work.

The basic idea is that you create a src/docs/guide directory and populate it with gdoc files. By prefixing the names of the gdoc files with appropriate numbers, you get a hierarchy of numbered sections. To get some idea of what you need to do, check out the source files that Luke Daley created for the Grails JMS plugin user guide.

Publishing the docs

Generating the documentation leaves you with a docs directory full of HTML files. What do you do with it? The next step is to get it onto your project-specific GitHub Pages site. Doing this manually is a bit of a bind, but I’ve created a Grails script and some template files that make it almost trivially easy (once you have the ‘gh-pages’ branch locally!).

First, copy this script to your $HOME/.grails/scripts directory. Next, switch to your ‘gh-pages’ branch and copy this HTML template to the root directory of the project. Next, create an index page for your site: index.html, index.textile, and index.markdown are all acceptable. Choose whichever format you prefer, but it should start with this section:

---
layout: main
title: My Grails Plugin
---

The three dashes are important! I’ll explain those and the layout/title later. Then,

$ git add main.html.tmpl
$ git add index.textile
$ git commit -m "Adding template layout and index page for GitHub Pages site."

In the above set of commands, replace ‘index.textile’ with the name of the index file you created.

You’re now ready to publish your plugin docs for the first time! Simply switch to the main branch and execute the new Grails command:

$ git checkout master
$ grails publish-github

Once the command successfully completes, you will find yourself back on the ‘gh-pages’ branch with all the documentation staged for a commit. You can then make any changes you want, commit everything, and then push the branch to GitHub. You can even do this in one step with the grails publish-github --push command, or if you want to automatically commit the documentation but not push, use grails publish-github --commit.

A few details

The publish-github command does a few things. First, it generates the plugin’s documentation via Grails’ doccommand. It then copies the generated documentation to the ‘gh-pages’ branch (using an rather ugly technique). Once it’s on the ‘gh-pages’ branch, it generates a new ‘main’ layout based on the main.html.tmpl file. It basically reads the information from the XML plugin descriptor, plugin.xml, and populates the template with things like the plugin version and author. The template is then generated to _layouts/main.html, which you can reference from your individual pages.

It’s up to you to write the site’s pages, but at least you have the option of three different syntax types. I prefer Textile for the moment, because it’s very similar to the gdoc format. The key part of each page is the header block, which you’ve seen already:

---
layout: main
title: My Grails Plugin
---

The ‘layout’ value is used to determine which file under _layouts to inject the page into. Ideally, the index page should use the _layouts/main.html template that the publish-github command generates, hence the value ‘main’. The ‘title’ option is specific to the generated template, which inserts the corresponding value into the title of the page. This is because it’s tough to get a suitable plugin name with correct capitalisation from the plugin descriptor.
Update Somebody has pointed out that the publish-github command doesn’t work if plugin.xml is committed to your main branch (typically master). You could try modifying the script to handle this, but the XML plugin descriptor doesn’t need to be in GitHub at all – it’s generated after all – so I would simply git rm it.

That’s pretty much it. You also have the full power of Jekyll (as described on the GitHub site), so you can build more elaborate sites as you see fit. If you want to see the results of all this jiggery-pokery, then take a look at the GWT plugin pages.

Until next time.

13 thoughts on “GitHub Pages: publish your Grails plugin docs

  1. Graeme Rocher

    Would be good if as many of these steps as possible were packages into a plugin so that once you have setup the ‘gh-pages’ tracking branch its as simple as:

    grails install-plugin github-pages
    grails publish-github –push

    To have a site published. The plugin could install the necessary templates and create the initial documentation structure etc.

    Come on Peter you know you want to 😉

  2. Peter Post author

    Of course I thought about it 🙂 In fact, a general GitHub plugin may be appropriate. It’d be a tiny plugin, but I guess that’s OK. To be honest, I’d prefer something that published direct to the plugin portal though.

  3. Mike Brevoort

    Very clever Peter. To Graeme’s point would be great if there were a more turnkey way to do this, but to me it would make sense that this would integrate more tightly into the Plugin Portal. I especially like the change notification on the plugin portal docs (though not 25 emails when someone is editing large changes and incrementally saving).

    Is it more appropriate to consider what improvements should be made to the plugin portal? Subpage support with the ability to publish all docs from script? Also, would be cool if within core a dev plugin there was a way to fire up a local webserver to serve the grails doc for the version you’re running as well as a consolidated collection of plugin docs for all the plugins installed in the project.

    I like the though of trying to maintain consolidated documentation for plugins.

  4. Pingback:   GitHub Pages: publica tu documentación de plugins de Grails (inglés) - Observatorio de Grails

  5. Pingback: Armbruster IT Blog » new Grails plugin released: modproxybalancer

  6. Luke Daley

    The following patch will make the publish-github script work with 1.3:

    — untitled
    +++ (clipboard)
    @@ -58,7 +58,13 @@
    // We have to generate the docs on the current branch because the
    // ‘docs’ target depends on ‘compile’, which of course requires all
    // the source files.
    – def docsDir = new File(“${basedir}/docs”)
    + def docsDir
    + try {
    + docsDir = grailsSettings.docsOutputDir
    + } catch (MissingPropertyException e) {
    + docsDir = new File(“${basedir}/docs”)
    + }
    +
    ant.delete(dir: docsDir.absolutePath)
    docs()

  7. Scott Ryan

    We tried the plugin on our community plugins and get a number of errors. The git url could not be located as it does not have a user name in it but is http://github.com/multi-tenant/grails-multi-tenant-core and then the script continued on and we got an error that the plugin.xml file was not found although the above post tells us to remove it. I tried packaging the plugin first but no luck there either. It would be cool if this was packaged into a plugin as it is rather tedious to set up for multiple projects with a lot of cutting and pasting which is error prone. I will keep pushing forward but any ideas would be helpful. I will try to post on the grails list as well.

  8. Peter Post author

    @Scott How do you plan to commit the pages if the clone’s remote URL is the HTTP one? That won’t allow you to push changes. Nonetheless, you’re right that the script is hardcoded to the git:// URL, when it could be https://.

    As for ‘plugin.xml’, note that the article says that it should be removed from the remote git repository. You do still need the file locally. The package-plugin command should create it, so I’m not sure what’s going on there.

    There’s nothing stopping you from creating a plugin out of this 🙂 In fact, a number of plugin developers seem to be using this approach, so I’m surprised a plugin hasn’t been created for it yet. I’m afraid I’ve barely used it since I created the script, so I’m rather loathe to create and maintain one. Perhaps this is something for the Grails Plugin Collective to manage.

  9. Pingback: "Hmm!" Ich erinnere mich Kästchen zwar geräumt, aber immer Frack, ein schimmernder Hut, adrette braune Gamaschen Mein Freund auf höchst eigenwillige Weise. | Schon so gut wie gewonnen.

  10. Chris

    Great post! I have been toying with the idea of building a plugin similar to the maven site plugin so that I can aggregate docs, coverage, metrics, etc. into one coherent site and this is a great starting point.

  11. Francis

    Hi Peter,

    Thanks very much for posting this, really helpful! I’d like to suggest one small fix for your PublishGithub.groovy script:

    Change:
    executeGit(“add docs _layouts”)

    To:
    executeGit(“add ${docsDir.toString() – basedir.toString()} _layouts”)

    Also, in case anyone couldn’t find it in the user guide (like me), the setting to change the docs output dir is the following (in grails-app/conf/BuildConfig.groovy):

    grails.project.docs.output.dir = “docs”

    Thanks again!

    Francis

Leave a Reply

Your email address will not be published. Required fields are marked *