Getting started with Sphinx

Source

Sphinx is a tool written in Python that automatically generates documentation from reST (restructured text) files.

Some popular libraries, tools using Sphinx:

In this article I'll show you how to:

  1. Setup the environment.

  2. Create simple reST files.

  3. Generate HTML documents from reST.

Get the sample project from github https://github.com/povilasb-com/sphinx-first-steps.

Setup the environment

I'll be using Debian 7.3 system. Get the neccessary packages:

sudo apt-get install sphinx-doc

Build initial project structure:

sphinx-quickstart

You will be prompted with many options. For the start I advise you to choose the default ones except for "Separate source and build directories" choose "Yes". This way you'll have a nice project structure with separated source and build directories:

$ ls
./build Makefile ./source

Create simple reST files

"reStructuredText is plaintext that uses simple and intuitive constructs to indicate the structure of a document." [2] Let's create a simple documentation consisting of two pages: main and contact pages. File structure would look like this:

$tree .
.
|__ build
|__ Makefile
|__ source
   |__ conf.py
   |__ index.rst
   |__ misc
      |__ contact.rst

Main page

By default the first page loaded is index.rst (it might be changed in conf.py). You might want to put brief description and table of contents into this page:

=====
Intro
=====

This is an index page of my documentation generated with Sphinx.
Checkout TOC for further info.

Content
=======

.. toctree::

        Contacts <misc/contact.rst>

Contacts page

This page might be as simple as a single table:

==========
Contact us
==========

+--------------+---------------+
| Mobile phone | +1xxxxxxx     |
+--------------+---------------+
| Email        + info@mail.com |
+--------------+---------------+

Generate HTML documents from reST

To genera html document from reST files simply invoke for the Makefile generated by sphinx-quickstart:

make html

This will build documentation in ./build/html. Open ./build/html/index.html in your browser to check it out.

References

Comments