Creating Read the Docs Documentation

While the Github wiki serves as a great place to dump raw / random pages, we've decided that the user-facing documentation should go on readthedocs. This involves dealing with a few hurdles:

• learning reStructuredText (.rst) markup language
• getting sphinx working locally in order to be able to preview changes

As an example of what we're going for, take a look at EdX's "Building and Running a Course" documentation: http://edx.readthedocs.org/projects/edx-partner-course-staff/en/latest/

And here's the raw source: /~https://github.com/edx/edx-platform/tree/master/docs/en_us/course_authors/source

NOTE: Github doesn't display .rst files correctly, so press 'Raw' to view the source)

reStructuredText

See: http://docutils.sourceforge.net/rst.html

Running Sphinx locally to preview changes

Install sphinx:

pip install sphinx

Install Read the Docs theme for sphinx:

pip install sphinx_rtd_theme

Navigate to the millstone docs/ directory and run:

make html

This generates the directory docs/_build/. Do not commit this ot Github (.gitignore should prevent this auotmatically).

To preview your changes, open docs/_build/html/index.html.

In order to view changes, once again run:

make html

Summary

• Keep adding random notes and pages to Github wiki
• Try to place user-facing / walk-through like information in our Read The Docs documentation
• Use sphinx to preview changes locally before making commits