This exercise will create a new documentation project for a student Journal.
Create a new repository in GitHub, naming it doc-journal.
Sphinxdoc documenation tools are installed using python package manager easy_install. Open a terminal to type in the command:
easy_install -U sphinx
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:
wget http://develop.aaltsys.info/resources/_downloads/.gitignore
wget http://develop.aaltsys.info/resources/_downloads/doc-addbranch.sh
wget http://develop.aaltsys.info/resources/_downloads/doc-newproject.sh
wget http://develop.aaltsys.info/resources/_downloads/doc-deploy.sh
After getting the files, click the gear icon on top of the left sidebar, and choose Refresh Project Tree to see the additions.
Hint
.gitignore is a hidden file. To see hidden files, click the gear icon and choose Show Hidden Files.
In your Cloud9 doc-journal workspace, open a terminal and type the command:
bash doc-newproject.sh
Note
The doc-newproject.sh 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 git@github.com:{_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.
Hint
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 conf.py and index.rst, if the title is unsuitable.
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.
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.
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:
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
:glob:
[0-9]*
Normally a developer would compile work and display the result locally during development.
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.
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:
bash doc-deploy.sh
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 doc-deploy.sh |
| View deployed site in browser | http:{_yourname_}.github.com/{_project_} |
Footnotes
| [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 http://git-scm.com/book. |
| [3] | Scott Chacon, Pro Git book source (written in MarkDown, not reST) repository on GitHub: https://github.com/progit/progit. |