Table Of Contents

Previous topic

Using Cloud9

Next topic

Using Heroku

This Page

Documentation Sample Project

This exercise will create a new documentation project for a student Journal.

Create a Project Workspace

In Your GitHub Account

Create a new repository in GitHub, naming it doc-journal.

  • Initialize it with a readme so it can be cloned.
  • Do not add a .gitignore now.
  • Click create repository.

In Your Cloud9 Account

  • At the top of the left menu, click on Your Account.
  • Expand PROJECTS ON GITHUB to show available projects.
  • Click doc-journal to select it.
  • Click the CLONE TO EDIT button.
  • In the Clone from URL dialog, click button CREATE.
  • Click the START EDITING button to open your project workspace.

Install Sphinxdoc in project

Sphinxdoc documenation tools are installed using python package manager easy_install. Open a terminal to type in the command:

easy_install -U sphinx

How To Get Files

Normally, if we wished to include some files in this project, we would download them from the following links:

Now here is the problem: the web browser downloads files to a local device, not to the Cloud9 workspace. To return files to Cloud9, use the Linux command wget instead. Copy and paste the following commands into a terminal window or into the console command line beneath an edit window:


After getting the files, click the gear icon on top of the left sidebar, and choose Refresh Project Tree to see the additions.


.gitignore is a hidden file. To see hidden files, click the gear icon and choose Show Hidden Files.

Initialize Sphinxdoc

In your Cloud9 doc-journal workspace, open a terminal and type the command:



The script runs right away in projects which are cloned from GitHub. Otherwise, the script requires the following two commands to be executed first:

git init
git remote add origin{_username_}/{_project_}.git

The Sphinxdoc quickstart asks these questions:

Root path for the documentation [.]:
Separate source and build directories (y/N) [n]:
Name prefix for templates and static dir [_]:
Project name: {_Cloud Development Journal_}
Author name(s): {_Your Name Here_}
Project version: {_1.0_}
Project release [1.0]:
Source file suffix [.rst]:
Name of your master document (without suffix) [index]:
Do you want to use the epub builder (y/N) [n]: {_y_}
autodoc: automatically insert docstringss from modules (y/N) [n]:
doctest: automatically test code snippets in doctest blocks (y/N) [n]:
intersphinx link between Sphinx documentation of different projects (y/N) [n]: {_y_}
todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
coverage: checks for documentation coverage (y/N) [n]:
pngmath: include math, rendered as PNG images (y/N) [n]:
mathjax: include math, rendered in the browser by MathJax (y/N) [n]:
ifconfig: conditional inclusion of content based on config values (y/N) [n]:
viewcode: include links to the source code of documented Python objects (y/N) [n]:
Create Makefile? (Y/n) [y]:
Create Windows command file? (Y/n) [y]: {_n_}

Be careful when answering these questions, as you get only one chance. Six questions have suggested answers (surrounded by underlines); the rest are defaulted. Type your answers NOT INCLUDING UNDERLINES.


Sphinx appends ‘s Documentation to the Project name. For example, the entry Cloud Development Journal will become the title Cloud Development Journal’s Documentation. Change the project title in the files and index.rst, if the title is unsuitable.

Write Documents

As with any discipline, software development requires a broad scope of expertise. Each area of computer knowledge addressed here should have a corresponding document in your journal. In this way, your journal will document your progress as an application developer.

What to write

Here is a list of suggested document topics for your journal:

Document identifier Description or Title
01_cloud-services.rst Notes on cloud services
02_bash-console.rst Linux BASH commands and their uses
03_bash-scripting.rst Writing programs as BASH scripts
04_rst-syntax.rst ReStructuredText documentation syntax
05_doc-projects.rst Documentation project repositories
06_ruby-syntax.rst Ruby programming language syntax notes
07_rails-guide.rst Rails web application framework notes
08_ruby-gems.rst Notes on Ruby gems aded to projects
09_other-addins.rst Other program additions (Twitter Bootstrap, e.g.)
10_ruby-projects.rst Ruby and Rails software projects
11_html-css.rst HTML and CSS syntax and notes
12_javascript.rst Javascript syntax and notes
13_project-mgmt.rst Collaborative development project management

Do not start out by creating all these documents. Create journal documents only as you encounter information which needs to be organized in its own topic.

How to write it

Each journal document must be written as a plain text document in the editor, using proper ReStructuredText markup [1] with added Sphinx features. Refer to the following resources to learn about document syntax:

Index your project

Notice that the topics listed previously are numbered. Sphinx has index commands to organize a series of numbered documents and build a table of contents for the project. For example, this project uses the following instructions to build part of the Table of Contents page:

Table of Contents:

.. toctree::
   :maxdepth: 2


Archive and Publish Site

Normally a developer would compile work and display the result locally during development.

Compiling and Previewing

This works at Cloud9, too. The Sphinx command to compile HTML pages from your documentation project is:

make clean html

To view the documents you have built, open the _build/html/index.html file in your Cloud9 project workspace. Then select Preview from the top menu.

Committing Repository

At the end of a day, or when a portion of work is finished, it should be committed and pushed to the GitHub repository. [2] Here are commands for that:

git add .
git status
git commit -m "commit message"
git push

Most of these actions are available from the Cloud9 menu as well.


Work should be deployed only when completed satisfactorily. Your project will be deployed at GitHub as a gh-pages repository branch. The command to deploy documentation in a gh-pages branch is:


Now the sequence of steps to build and deploy output might be:

Development Step Corresponding terminal command
Edit documents  
Check for compile errors make clean html
Preview changes in browser cloud9 Preview
Add changes to git tracking git add .
View repository status git status
Commit changes to repository git commit -m "commit message"
Push to remote at GitHub git push
Build and deploy gh-pages bash
View deployed site in browser http:{_yourname_}{_project_}


[1]Davenport’s Re-Structured Text Syntax.
[2]Scott Chacon, Pro Git (August 27, 2009, ISBN-10: 1430218339), available at Amazon, or for free on-line at
[3]Scott Chacon, Pro Git book source (written in MarkDown, not reST) repository on GitHub: