Document Management - Sphinx

"Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.", says the official web site of Sphinx.

In my opinion, Sphinx is a tool to generate document by coding the contents, especial more focused on writing manuals or specifications, as not only coding document but creating diagram images such as actdiag, blockdiag, nwdiag, and seqdiag.

• official

• Documentation in English

• Sphinx-Users.jp

• Documentation in Japanese

Now, I'm going to list the installation process of Sphinx.

The platform is the same with before when installing Alfresco.

OS	CentOS release 5.7 (Final)
Kernel	2.6.18-274.el5 x86_64
Package group	Development Libraries  Dialup Networking Support  GNOME Software Development  Legacy Software Development  Legacy Software Support  Mail Server  Network Servers  System Tools  Yum Utilities
Python	python26-2.6.5-6.el5 python26-devel-2.6.5-6.el5 python26-distribute-0.6.10-4.el5 python-imaging-1.1.7-4.el5 python-imaging-devel-1.1.7-4.el5 python26-libs-2.6.5-6.el5 python-setuptools-0.6

The extended modules for sphinx and their roles are below.

sphinx	Sphinx core package
rst2pdf	Generate PDF
blockdiag	Generate block-diagram image
sphinxcontrib-blockdiag	Embed block-diagram
seqdiag	Generate sequence-diagram image
sphinxcontrib-seqdiag	Embed sequence-diagram image
actdiag	Generate activity-diagram image
sphinxcontrib-actdiag	Embed  activity-diagram image
nwdiag	Generate network-diagram image
sphinxcontrib-nwdiag	Embed network-diagram image

• Install epel repository

$ wget http://download.fedora.redhat.com/pub//5/x86_64/epel-release-5-4.noarch.rpm
$ sudo rpm -ivh -release-5-4.noarch.rpm
$ sudo sed -i 's/enabled=1/enabled=0/' /etc/yum.repos.d/epel.repo

•  Install python-2.6

$ sudo yum -y --enablerepo=epel install python26 python26-libs python26-devel python-imaging python-imaging-devel python-setuptools

•   Install sphinx and the extended modules

$ sudo easy_install-2.6 sphinx
$ sudo easy_install-2.6 rst2pdf
$ sudo easy_install-2.6 blockdiag
$ sudo easy_install-2.6 sphinxcontrib-blockdiag
$ sudo easy_install-2.6 seqdiag
$ sudo easy_install-2.6 sphinxcontrib-seqdiag
$ sudo easy_install-2.6 actdiag
$ sudo easy_install-2.6 sphinxcontrib-actdiag
$ sudo easy_install-2.6 nwdiag
$ sudo easy_install-2.6 sphinxcontrib-nwdiag

 After installing Sphinx, let's create a sample project to examine its befavior.

• Setup the document source

$ sudo sphinx-quickstart

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]: project

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation.
> Project name: Experiment
> Author name(s): naoya hashimoto

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 1.00
> Project release [1.00]:

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]: y

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: y
> coverage: checks for documentation coverage (y/N) [n]: y
> pngmath: include math, rendered as PNG images (y/N) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/N) [n]: y
Note: pngmath and mathjax cannot be enabled at the same time.
pngmath has been deselected.
> ifconfig: conditional inclusion of content based on config values (y/N) [n]: y
> viewcode: include links to the source code of documented Python objects (y/N) [n]: y

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]: y
> Create Windows command file? (Y/n) [y]: y

Creating file project/source/conf.py.
Creating file project/source/index.rst.
Creating file project/Makefile.
Creating file project/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file project/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

•  Define document structure

$ cd project
$ vim source/index.rst
 1 .. Experiment documentation master file, created by
 2    sphinx-quickstart on Sun Dec 11 15:10:10 2011.
 3    You can adapt this file completely to your liking, but it should at least
 4    contain the root `toctree` directive.
 5
 6 Welcome to Experiment's documentation!
 7 ======================================
 8
 9 Contents:
10
11 .. toctree::
12    :maxdepth: 2
13
14    expert_python  : ←Added the title of child file
15
16 Indices and tables
17 ==================
18
19 * :ref:`genindex`
20 * :ref:`modindex`
21 * :ref:`search`

•  Add content

$ cat > source/expert_python.rst << EOF
=========================
Expert Python Programming
=========================

:著者: Tarek
:出版社: Packt Publishing

内容
====

Pythonのエキスパート向けの本。Pythonの内部のアルゴリズムにも言及しつつ
マニアックな文法の適切な使い方の紹介に始まり、アジャイルソフトウェア開発
をPythonで行うためのテストツール、継続的インテグレーションのツールなどの
紹介や、よりよいプログラムのための、Pythonのためのデザインパターン、
パフォーマンスチューニングなど、幅広く、深い内容の本。
EOF

•  Build the content

$ make html
sphinx-build -b html -d build/doctrees   source build/html
Making output directory...
Running Sphinx v1.1.2
loading pickled environment... not yet created
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
writing additional files... (0 module code pages) genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in build/html.

•  See the content

Finally, it's just practical, but I'll show a tiny example of listing the activate services with chkconfig command.

{ echo "
chkconfig list
--------------

.. csv-table:: Daemon
   :header: "Daemon", "0", "1", "2", "3", "4", "5", "6"
   :widths: 50, 10, 10, 10, 10, 10, 10, 10

" ;
chkconfig --list | sort | perl -pe 's/\s*(\d:)?([^\s]+) */,"$2"/g' | sed -e 's/^,/   /' ;
} >> system_daemon.rst

• the source file

$ cat system_daemon.rst
.. csv-table:: Daemon
   :header: "Daemon", "0", "1", "2", "3", "4", "5", "6"
   :widths: 50, 10, 10, 10, 10, 10, 10, 10

   "NetworkManager","off","off","off","off","off","off","off"
   "acpid","off","off","on","on","on","on","off"
   "alfresco","off","off","on","on","on","on","off"
   "anacron","off","off","on","on","on","on","off"
   "atd","off","off","off","off","off","off","off"
   "auditd","off","off","on","on","on","on","off"
   "autofs","off","off","off","off","off","off","off"
   "avahi-daemon","off","off","off","off","off","off","off"
   "avahi-dnsconfd","off","off","off","off","off","off","off"
   "bluetooth","off","off","off","off","off","off","off"
   "conman","off","off","off","off","off","off","off"
   "cpuspeed","off","on","on","on","on","on","off"
   "crond","off","off","on","on","on","on","off"
   "dnsmasq","off","off","off","off","off","off","off"
   "dund","off","off","off","off","off","off","off"
   "firstboot","off","off","off","on","off","on","off"
   "gpm","off","off","on","on","on","on","off"
   "haldaemon","off","off","off","off","off","off","off"
   "hidd","off","off","on","on","on","on","off"
   "ip6tables","off","off","off","off","off","off","off"
   "iptables","off","off","off","off","off","off","off"
   "irda","off","off","off","off","off","off","off"
   "irqbalance","off","off","on","on","on","on","off"
   "iscsi","off","off","off","off","off","off","off"
   "iscsid","off","off","off","off","off","off","off"
   "kudzu","off","off","off","off","off","off","off"
   "lvm2-monitor","off","on","on","on","on","on","off"
   "mcstrans","off","off","off","off","off","off","off"
   "mdmonitor","off","off","off","off","off","off","off"
   "mdmpd","off","off","off","off","off","off","off"
   "messagebus","off","off","off","on","on","on","off"
   "microcode_ctl","off","off","on","on","on","on","off"
   "multipathd","off","off","off","off","off","off","off"
   "netconsole","off","off","off","off","off","off","off"
   "netfs","off","off","off","off","off","off","off"
   "netplugd","off","off","off","off","off","off","off"
   "network","off","off","on","on","on","on","off"
   "nfs","off","off","off","off","off","off","off"
   "nfslock","off","off","off","off","off","off","off"
   "nscd","off","off","off","off","off","off","off"
   "oddjobd","off","off","off","off","off","off","off"
   "pand","off","off","off","off","off","off","off"
   "pcscd","off","off","off","off","off","off","off"
   "portmap","off","off","off","off","off","off","off"
   "postgresql-9.1","off","off","on","on","on","on","off"
   "psacct","off","off","off","off","off","off","off"
   "rawdevices","off","off","off","on","on","on","off"
   "rdisc","off","off","off","off","off","off","off"
   "readahead_early","off","off","on","on","on","on","off"
   "readahead_later","off","off","off","off","off","on","off"
   "restorecond","off","off","off","off","off","off","off"
   "rpcgssd","off","off","off","off","off","off","off"
   "rpcidmapd","off","off","off","off","off","off","off"
   "rpcsvcgssd","off","off","off","off","off","off","off"
   "saslauthd","off","off","off","off","off","off","off"
   "sendmail","off","off","off","off","off","off","off"
   "smartd","off","off","off","off","off","off","off"
   "sshd","off","off","on","on","on","on","off"
   "svnserve","off","off","off","off","off","off","off"
   "syslog","off","off","on","on","on","on","off"
   "tcsd","off","off","off","off","off","off","off"
   "vmware-tools","off","off","on","on","off","on","off"
   "wpa_supplicant","off","off","off","off","off","off","off"
   "xfs","off","off","off","off","off","off","off"
   "ypbind","off","off","off","off","off","off","off"
   "yum-updatesd","off","off","off","off","off","off","off"

• the output image

Daemon

Daemon	0	1	2	3	4	5	6
NetworkManager	off	off	off	off	off	off	off
acpid	off	off	on	on	on	on	off
alfresco	off	off	on	on	on	on	off
anacron	off	off	on	on	on	on	off
atd	off	off	off	off	off	off	off
auditd	off	off	on	on	on	on	off
autofs	off	off	off	off	off	off	off
avahi-daemon	off	off	off	off	off	off	off
avahi-dnsconfd	off	off	off	off	off	off	off
bluetooth	off	off	off	off	off	off	off
conman	off	off	off	off	off	off	off
cpuspeed	off	on	on	on	on	on	off
crond	off	off	on	on	on	on	off
dnsmasq	off	off	off	off	off	off	off
dund	off	off	off	off	off	off	off
firstboot	off	off	off	on	off	on	off
gpm	off	off	on	on	on	on	off
haldaemon	off	off	off	off	off	off	off
hidd	off	off	on	on	on	on	off
ip6tables	off	off	off	off	off	off	off
iptables	off	off	off	off	off	off	off
irda	off	off	off	off	off	off	off
irqbalance	off	off	on	on	on	on	off
iscsi	off	off	off	off	off	off	off
iscsid	off	off	off	off	off	off	off
kudzu	off	off	off	off	off	off	off
lvm2-monitor	off	on	on	on	on	on	off
mcstrans	off	off	off	off	off	off	off
mdmonitor	off	off	off	off	off	off	off
mdmpd	off	off	off	off	off	off	off
messagebus	off	off	off	on	on	on	off
microcode_ctl	off	off	on	on	on	on	off
multipathd	off	off	off	off	off	off	off
netconsole	off	off	off	off	off	off	off
netfs	off	off	off	off	off	off	off
netplugd	off	off	off	off	off	off	off
network	off	off	on	on	on	on	off
nfs	off	off	off	off	off	off	off
nfslock	off	off	off	off	off	off	off
nscd	off	off	off	off	off	off	off
oddjobd	off	off	off	off	off	off	off
pand	off	off	off	off	off	off	off
pcscd	off	off	off	off	off	off	off
portmap	off	off	off	off	off	off	off
postgresql-9.1	off	off	on	on	on	on	off
psacct	off	off	off	off	off	off	off
rawdevices	off	off	off	on	on	on	off
rdisc	off	off	off	off	off	off	off
readahead_early	off	off	on	on	on	on	off
readahead_later	off	off	off	off	off	on	off
restorecond	off	off	off	off	off	off	off
rpcgssd	off	off	off	off	off	off	off
rpcidmapd	off	off	off	off	off	off	off
rpcsvcgssd	off	off	off	off	off	off	off
saslauthd	off	off	off	off	off	off	off
sendmail	off	off	off	off	off	off	off
smartd	off	off	off	off	off	off	off
sshd	off	off	on	on	on	on	off
svnserve	off	off	off	off	off	off	off
syslog	off	off	on	on	on	on	off
tcsd	off	off	off	off	off	off	off
vmware-tools	off	off	on	on	off	on	off
wpa_supplicant	off	off	off	off	off	off	off
xfs	off	off	off	off	off	off	off
ypbind	off	off	off	off	off	off	off
yum-updatesd	off	off	off	off	off	off	off