Painless Documentation - Part 1 reStructuredText

Of course, whenever we start a project, making things work is always the number one priority. Sometimes (maybe more often than we'd like), documentation is an after thought. So how do we make documentation as painless as possible but yet communicate the message we want? reStructuredText and Sphinx come to the rescue. :)

The documentation page for reStructuredText is excellent (wouldn't it be ironic if it isn't?). So I am not going to repeat the tutorial or examples, here are the links:

- Example: http://docutils.sourceforge.net/docutils/statemachine.py

- QuickStart: http://docutils.sourceforge.net/docs/user/rst/quickstart.html

- Quick Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html  

- Cheatsheet:

http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt

- Render Test

http://www.tele3.cz/jbar/rest/rest.html

9 out of 10 times, for my documentation, I just need: 

• Title, subtitle
• Sectional breakouts
• Paragraphs
• Images
• Code (unmodified text)
• Hyperlink

Here is my simple example that includes all of the above: 

*** Start ***

====================

Datacenter

====================

--------------

by Eric Chou

--------------

Overview

====================

  This is an overview of the Datacenter. 

  * Scalable

  * Always Up

    - 99.995%

    - Geographically redundant

Topology 

====================

Internet Connectivity

---------------------------

Inside Wiring

---------------------------

Language of Choice

====================

http://www.python.org

.. image:: http://www.python.org/community/logos/python-powered-w-200x80.png

Code::

  

  ** "print hello world"

*** Finish ***

Plug this text into the render site, here is what you would get:

Not to shabby for a few lines of text. In the next post, we will use this rst file format to construct HTML pages using Sphinx. 

Happy Coding!