How to work with the jQPlot end user documentation

Background

End user documentation is found at http://svandecappelle.github.io/jQPlot/ - these are so called GitHub Pages. As GH Pages supports Jekyll directly, our end user documentation does also use Jekyll.

GitHub Pages are based on a branch in the repository called gh-pages. When pushing into this branch, your changes will appear on your http://github.io/ page.

What you need to get started

This wiki page will not teach you these things, but they are a prerequisite for working with the jQPlot end user documentation.

• Your own fork of the svandecappelle/jQPlot repository.
• A git client, and knowledge about how to use push and pull with GitHub.
• A setup where you can install Ruby gems.
• A good code editor.

How to get started

The following information is based on GitHub Pages documentation and a Anna Debenham Get Started With GitHub Pages.

All instructions are for Unix derivates (Unix, *BSD, Linux and OSX). Feel free to add instructions for Windows.

1. Install Jekyll

We will not go into details on how to install Jekyll, without Ruby in place, as this is out of scope for this wiki page. If you have Ruby in place, all you need to do is run the following command:

MyMachine$ sudo gem install jekyll

2. Clone your GitHub jQPlot repository

If you contribute both to the jQPlot code, AND the documentation, you'll need two local jQPlot clones. One clone for the main jQPlot code, and one clone for the jQPlot GitHub Pages. The reason is that the gh-pages branch is detached from the other branches (this is really a quirk on behalf of GitHub Pages).

The following commands will create a new directory called jqplot-doc and clone your jQPlot repository locally.

YourMachine$ mkdir jqplot-doc
YourMachine$ cd jqplot-doc/
YourMachine$ git clone git@github.com:<YourGitHubUserName>/jQPlot.git .

3. Detach the gh-pages branch

The following command will detach the gh-pages branch, and remove everything else.

YourMachine$ git symbolic-ref HEAD refs/heads/gh-pages
YourMachine$ rm .git/index
YourMachine$ git clean -fdx
YourMachine$ git checkout gh-pages

4. Serve Jekyll pages locally

Instead constantly pushing your changes to GitHub and relaoding http://.github.io/jQPlot/, you can let jekyll serve files locally. When you do this, all you have to do is edit and save the file you are working on, and then press reload in your browser.

Example of starting jekyll on a Unix-derivate:

YourMachine$ jekyll serve
Configuration file: /Users/You/kode/jqplot-doc/_config.yml
            Source: /Users/You/kode/jqplot-doc
       Destination: /Users/You/kode/jqplot-doc/_site
      Generating...
                    done.
 Auto-regeneration: enabled for '/Users/You/kode/jqplot-doc'
Configuration file: /Users/You/kode/jqplot-doc/_config.yml
    Server address: http://127.0.0.1:4000/jQPlot/
  Server running... press ctrl-c to stop.

This will start a local webserver on port 4000. Just point a web browser to http://127.0.0.1:4000/jQPlot/ and you are good to go.

Now what?

Before starting your editing, read the README.md file in the gh-pages branch as it contains documentation on actually how to work with the jQPlot end user documentation.

You are now ready to work with the documentation and issue Pull-requests back to the svandecappelle/jQPlot repository.

Synchronizing with svandecappelle/jQPlot

To get synchronized with the core repo, svandecappelle/jQPlot, you need to set up this repository as the upstream repo.

First you need to add svandecappelle/jQPlot as the remote repo:

 git remote add upstream https://github.com/svandecappelle/jQPlot

To verify that this is correct, issue git remote -v, your output should look like a derivative of the following:

origin         git@github.com:YourGitHubAccount/jQPlot.git (fetch)
origin         git@github.com:YourGitHubAccount/jQPlot.git (push)
upstream       https://github.com/svandecappelle/jQPlot (fetch)
upstream       https://github.com/svandecappelle/jQPlot (push)

Now the workflow is as follows when you want to sync your own GitHub repository:

1. Pull changes from the upstream: git pull upstream gh-pages
2. Fix merge conflicts, if any
3. Commit merge: git commit
4. Push to your own remote GitHub repo: git push