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!