Creating a web page for your toolkit

[Note: throughout this document, "you" refers to the set of people with push permissions on a particular repository.]

This document describes how to setup and keep updated a web page describing your IBMStreams toolkit. It is currently in draft form; discuss here, but feel free to edit.

Creating an initial web page

GitHub makes it very easy to create a web page for your project. There are directions here here for creating an initial project page, however, you may not have the permissions necessary to access the repository settings. In that case, ask in an issue for the initial web page to be created.

The web content is stored in the gh-pages branch of your repository. When the the gh-pages branch is initially created by the process above, an index.html file is also created. The gh-pages branch does NOT contain any of your code.

After the index.html file is created, you'll want to edit it to replace the boilerplate text with text of your own.

Adding SPLDoc to your web page

You will probably want to have you web page link to SPL doc for your operators. To make the process of updating that easier, you can use the updateWeb.pl script (currently found in the streams.inet repository).

This script calls ant targets, and so it assumes that there is a top-level build.xml similar to the one in streamsx.inet. That build file is fairly generic, so you should be able to copy it and make only a few changes and have it work for your project. You'll also need a build.xml in your toolkit directory itself.

Run the script from your repository on the master branch via

updateWeb.pl --createTempRepository --push

The script will then:

• run the spldoc target in your top-level build file. This target should make documents.
• clone a copy of your repository in '/tmp'
• change branch of the '/tmp/streamsx.abc' to 'gh-pages'
• search through all directories in the repository (samples and toolkit) to find spldoc, and copy from your current directory to the 'gh-pages' branch
• make an update to the samples list in index.html as described below
• commit any changes
• push the gh-pages changes to the gh-pages branch
• delete the '/tmp/streamsx.abc' directory

The result is that your spl doc will be updated.

If you want to run the script but not push your changes, specify the --nodeleteTemp option, eg updateWeb.pl --createTempRepository --nodeleteTemp

It will leave a clone of the repository, with the branch set to gh-pages, in /tmp. For example, on streamsx.inet, the /tmp/streamsx.inet directory will contain the all the web artifacts.

Updating the samples list

You will need to explicitly edit your index.html to point to your toolkit documentation. (See the streamsx.inet index.html)

To make it easier to maintain the list of samples, the updateWeb.pl script will automatically generate a list of samples with links to their documentation. To do this, add a line <!-- BEGIN SAMPLE LIST --> and <!-- END SAMPLE LIST -->. The lines between these will be replaced with a list of the samples found.

More on updateWeb.pl

Instead of specifying --createTempRepository you may specify on the command line a second, already created clone of the same repository (eg, updateWeb.pl $HOME/web-repos/streamsx.abc). In this mode, you'll have one clone set to the master branch (ie, where you usually do your work), and you'll create a second clone just for updating the web page. To create this clone, use the exact same URL and the process as you used to create your normal working copy. For the command above, the user has created a web-repos directory under their home directory and run git clone <urlForStreamsx.abc> in that directory.

Run the script from the clone where you usually do your work (ie, NOT the 'web-repos/streamx.abc')

The script will attempt to checkout gh-pages in the clone specified on the command line, and make all updates to the docs in that repository. This can run into errors if the checkout of gh-pages fails or if the gh-pages branch is not up-to-date in that repository.

Other options:

• --commit: commit after adding files (default)
• --nocommit: do not commit. Does not make sense with the --push option.
• --push: push update. Required if --createTempRepository is specified.
• --nopush: do not push the files (default)

Automatically updating web pages

If you have a system like Jenkins that polls the repository, you can set it to automatically update the web pages on a successful build.