Saturday, June 15, 2013

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:

- Cheatsheet:
- Render Test

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 ***

by Eric Chou


  This is an overview of the Datacenter. 

  * Scalable
  * Always Up
    - 99.995%
    - Geographically redundant


Internet Connectivity

Inside Wiring

Language of Choice

.. image::

  ** "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! 

No comments:

Post a Comment