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:
Setup the environment.
Create simple reST files.
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:
Build initial project structure:
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:
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
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>
This page might be as simple as a single table:
========== Contact us ========== +--------------+---------------+ | Mobile phone | +1xxxxxxx | +--------------+---------------+ | Email + firstname.lastname@example.org | +--------------+---------------+
Generate HTML documents from reST
To genera html document from reST files simply invoke for the Makefile generated by sphinx-quickstart:
This will build documentation in ./build/html. Open ./build/html/index.html in your browser to check it out.