Monday, December 19, 2011

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.



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

5 comments:

  1. Document scanning is very useful and mostly used service. As we need document imaging as , There are various firms like Tarheel Imaging Inc which uses various tools to provide this service , so we have to choose much professional for this purpose.

    ReplyDelete
    Replies
    1. I totally agree with you. I am not actually professional on the area, but as I have been writing manual or specification for years, I did realize that how important it is to write them with fun!

      Delete


    2. Trên mặt Lão ma Bàn Thiên không ngừng run rẩy, nhưng trong lòng thì vạn phần không muốn, hắn đương nhiên biết rõ trữ vật giới chỉ trên thân Triệu Tuệ Quang đã đến trước mắt người thanh niên, nhưng mà người thanh niên này hắn cảm thấy không dễ chọc, chỉ có thể nhịn đau ly khai, truy đuổi Triệu Tuệ Quang mộtdongtam
      mu moi ra hom nay
      tim phong tro
      http://nhatroso.com/
      nhac san cuc manh
      tổng đài tư vấn luật
      http://dichvu.tuvanphapluattructuyen.com/
      văn phòng luật hà nội
      tổng đài tư vấn luật
      thành lập công ty trọn gói
      http://we-cooking.com/
      chém gió
      trung tâm ngoại ngữ ngày, cuối cùng tiện nghi cho người khác.

      - Ta nói rồi, không dựa theo ước định là chết.

      Nhạc Thành lạnh lùng nói.

      Trên mặt Lão ma Bàn Thiên run rẩy lên, hắn đã nhượng bộ, có thể làm cho hắn nhượng bộ đến trình độ không có mấy người, mà người thanh niên trước mắt này, tựa hồ không muốn buông tay. Thân là tứ tinh cường giả Đấu Thánh, hắn cũng không phải là người sợ phiền phức, nhưng ở bên trong Cực Viêm, hắn không muốn lưỡng bại câu thương mà thôi, để tránh cho những người khác chiếm tiện nghi, hắn còn chưa tin người thanh niên trước mắt này còn có thể ngăn được hắn.

      - Hừ, tiểu tử, không nên quá đáng như vậy, ngươi tưởng lão ma sợ ngươi hay sao.

      Delete
  2. Hi, nice post. This is an interesting and very informative topic. Thanks for sharing your ideas on document management, its not just entertaining but also gives your reader knowledge. Good blogs style too, Cheers!
    By choosing a full-featured software suite that performs a number of inter-office duties like document and data capture, indexing, retrieval, editing, annotation and more, you give your company and individual team members more time to focus on other important roles that make your business a success.

    ReplyDelete
    Replies
    1. Thanks for your comment. I agree with you on document management not being entertaining but important. Writing document seems boring especially about manual, I guess. But it is interesting to find joy in something which looks boring.

      Delete