Skip to content

Contributing Documentation

Jump to bottom
kathyssaunders edited this page Feb 28, 2016 · 20 revisions

How do I contribute Quarks documentation?

I was new to both Git and the technologies Quarks uses to generate documentation; based on my experience, this is a detailed description of what is involved. Feel free to fix errors or add your own comments. The Quarks documentation repository is here.

Overview of the quarks-edge repositories

I found it useful to take a look at some of the projects in quarks-edge to understand what to contribute where. At the time I am writing this, there are 3 projects in quarks-edge that I want to describe.

  1. quarks - The quarks repository contains the Quarks code itself. Go here for updating and contributing code, examples, tests, javadoc, etc.

  2. quarks-edge.github.io - The quarks-edge.github.io repository contains the files needed to display our io site (or main web page).

  3. quarks.documentation - The quarks.documentation repository contains the files needed to generate the content on the documentation home page and the various documentation pages it links to. The rest of this wiki page describes how to make contributions to quarks.documentation.

Install needed software

  • You probably already have Git installed on your machine; you will need it to contribute doc.
  • You can use your favorite editor for creating or editing Markdown documents. I found Atom to be a good editor for Markdown.
  • Quarks uses Jekyll to generate html from Markdown. Jekyll does not officially support Windows, but it will work. I have a Windows 7 machine and found these instructions very useful. I followed them carefully and all seems to be working well.

Set up your repository

You will need to fork the quarks-edge/quarks-documentation and create a local clone. Read about how to create a fork and create a local clone here. Make sure you sync regularly so you have the latest changes. Please note that you will need to replace "master" with "gh-pages" when implementing the examples referenced in the Syncing a fork document.

Run Jekyll

You will need to run Jekyll on your machine in order to preview your doc changes locally. In order to start Jekyll, you will need a shell. On my Windows machine, I use Git Bash (which comes as part of your Git installation) to start Jekyll. First cd to the root directory of the quarks.documentation repository on your machine. On my machine:

$ cd /c/quarks.documentation

Start jekyll:

$ jekyll serve

The Jekyll server will start and print informational messages to your screen. Towards the end of the messages, find the Server Address message:

 Server address: http://127.0.0.1:4010/quarks.documentation/

Copy the url from the server address message and paste it into your browser. You will see the documentation home page running from the local quarks.documentation repository on your machine.

Edit or create documentation files

Keep Jekyll running on your local machine as you work on the documentation files. Quarks uses Markdown for formatting text in our documentation files. The Writing on Github page is a good introduction to Markdown. I found the Markdown Cheatsheet to be very useful.

You will find most of the documents in quarks.documentation/docs/quarks. For example, if you wanted to edit the Getting Started information, use your editor to open that file at quarks.documentation/docs/quarks/quarks-getting-started.md. If you are creating a new markdown file for our documentation, you will need the following header at the very top of the file. For example:

---
layout: docs
title: Getting Started
description:  Quarks Getting Started
weight: 10
---

The layout field refers to one of the html files in documentation/docs/_layouts. The most commonly used value is "docs".

The weight field defines the relative location of your document to others on the documentation home page. For example, if quarks-getting-started.md has a weight of 10, and common-quarks-operations.md has a weight of 11, then "Common Quarks Operations" will be listed after "Getting Started" on the documentation home page.

I found Jekyll to be very sensitive to white space, so make sure you have no trailing spaces in your header, particularly after "---".

When you save your Markdown file, Jekyll will automatically generate html and store it in the directory structure under quarks.documentation/_site. To view the final web page, use the URL you saved above from the Jekyll server output. Be sure to refresh.

Create a pull request

Once you have finished editing and testing your Markdown files, complete your Git checkins for your Markdown files, images, or other files you have added and create your pull request. You do not need to check in the html files as those will be generated automatically once your pull request is merged.

Clone this wiki locally