"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.
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 |
$ 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
$ 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`
$ cat > source/expert_python.rst << EOF
=========================
Expert Python Programming
=========================
:著者: Tarek
:出版社: Packt Publishing
内容
====
Pythonのエキスパート向けの本。Pythonの内部のアルゴリズムにも言及しつつ
マニアックな文法の適切な使い方の紹介に始まり、アジャイルソフトウェア開発
をPythonで行うためのテストツール、継続的インテグレーションのツールなどの
紹介や、よりよいプログラムのための、Pythonのためのデザインパターン、
パフォーマンスチューニングなど、幅広く、深い内容の本。
EOF
$ 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.
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
$ 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"
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 |
