Painless Documentation - Part 2 Sphinx

In the last post, we use reStructuredText to build a simple HTML page. Let's use Sphinx to put some structure around it. Again, Sphinx documentation is excellent, here are the links I used to build my pages:

Tutorial: http://sphinx-doc.org/tutorial.html

TOC Tree: http://sphinx-doc.org/markup/toctree.html#toctree-directive

After the usual 'pip install', in my scenario, I also used https://pypi.python.org/pypi/virtualenv to isolate my environment. After that, just follow the tutorial steps: 

1. Start the procject and accept most of the defaults:

Sphinx)$ sphinx-quickstart Datacenters

Welcome to the Sphinx 1.2b1 quickstart utility.

Please enter values for the following settings (just press Enter to

accept a default value, if one is given in brackets).

Selected root path: Datacenters

<skip>

2. A Datacenter folder will be created, in there there will be a source/ folder that contains the initial index.rst file:

(Sphinx)$ ls

Datacenters bin include lib

(Sphinx)$ 

(Sphinx)$ cd Datacenters/

(Sphinx)$ ls source/

_static _templates conf.py index.rst

(Sphinx)$

3. Modify the index.rst file for the table of contents to group together the future pages:

(Sphinx)$ vi source/index.rst 

  6 Welcome to Datacenters's documentation!

  7 =======================================

  8 

  9 Contents:

 10 

 11 .. toctree::

 12    :maxdepth: 1

 13 

 14    intro

 15    dc1

 16    dc2

4. Then create each of the intro.rst, dc1.rst, and dc2.rst files (see last post for structure): 

(Sphinx)$ cat source/intro.rst 

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

Intro

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

(Sphinx)$ cat source/dc1.rst 

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

DC1

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

Overview

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

  This is an overview of the DC1 

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

(Sphinx)$ cat source/dc2.rst 

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

DC2

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

Overview

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

  This is an overview of the DC2

  * Not Scalable

  * Usually Up

    - Not 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"

(Sphinx)$ 

5. Run the build (I have already built mine so your output will be different):

(Sphinx)$ sphinx-build -b html source outputDir

Running Sphinx v1.2b1

loading pickled environment... done

building [html]: targets for 0 source files that are out of date

updating environment: 0 added, 0 changed, 0 removed

looking for now-outdated files... none found

no targets are out of date.

(Sphinx)$ 

6. Navigate to the outputDir directory and you will find all the pages:

And you get the search function for free. How cool is that? Try search for DC1 in the Quick Search box. 

Really, after the initial build, it took me a lot longer to write this post than build a new project. Painless documentation at its best. 

Happy coding! 

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!