sphinx tips: add subsubsection into pdf compiled by make all-pdf-ja

When sphinx compiles latex files, it chooses cls file which written in conf.py.

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents =
   ('index', 'sample_document.tex', u'This is sample',
     u'Author Name', 'manual'),
]

If 'manual' is specified in conf.py, sphinx read sphinxmanual.cls when it compiles latex file. So, if you want to enable subsubsection, you should edit sphinxmanual.cls or other specified cls file. In my environment, original sphinxmanual.cls is located in /usr/local/lib/python2.6/dist-packages/Sphinx-1.0.7-py2.6.egg/sphinx/texinputs/sphinxmanual.cls. And you can enable subsubsection with editing this cls file like below.

before:
\setcounter{secnumdepth}{2}

after:
\setcounter{secnumdepth}{3}

enjoy.

sphinx tips: generate center-aligned table in pdf document

When we type 'make latex' command in sphinx root directory, sphinx generates set of latex files from rst files based on '/usr/share/pyshared/sphinx/writers/latex.py' which defines rules for generating latex files. If you do not like default behavior of latex generator, you can change it by modifying the code.

Sometimes I was annoyed by left-aligned table which is automatically created by using csv-table directive when creating a pdf document. So, I changed some part of latex.py. Below is difference between original latex.py and bit-of modified latex.py which can generate center-aligned table by using csv-table.

( ... just added '\begin{center}' and '\end{center}' command )

617c617
<             self.body.append('\n\\begin{threeparttable}\n'
---
>             self.body.append('\n\\begin{center}\n\\begin{threeparttable}\n'
664c664
<             self.body.append('\\end{threeparttable}\n\n')
---
>             self.body.append('\\end{threeparttable}\n\\end{center}\n\n')

sphinx tips: how to easily write a document for several scripts?

Today, I explain how to write a sphinx document for several scripts in an easy way. Assume that you are now writing postgres scripts and need to write document for them. Now, you have two postgres scripts named sample{1,2}.sql and these scripts are written like below.

-- Sample1.sql
-- -----------

-- This SQL does something!!
-- A definition of sample_table shown below.

-- =============== =========== ============
-- Column Name     Type        Description
-- =============== =========== ============
-- foo             TEXT        foo?
-- bar             TEXT        bar?
-- baz             FLOAT       baz?
-- =============== =========== ============

-- :NOTE: just return 10 records
-- :TODO: just return 11 records

-- .. code-block:: sql
--    :linenos:

SELECT
    *
FROM
    sample_table
LIMIT 10;

-- Sample2.sql
-- -----------

-- This SQL extract data from columns named foo, bar...

-- :NOTE: just return 10 records
-- :TODO: just return 11 records

-- .. code-block:: sql
--    :linenos:

SELECT
    foo,
    bar
FROM
    sample_table
LIMIT 11;

As you can see above, there are rst formatted comments in sql scripts. If you write this kind of comments in sql scripts, you can easily convert them to html/latex-styled pdf! Below shell scripts can convert above sql scripts into one rst document.

#!/bin/sh
# convert_sql2rst.sh

output_rst="sample.rst"

if [ -e ${output_rst} ]; then
    rm ${output_rst}
fi

echo "=======================" >> ${output_rst}
echo "This is sample chapter!" >> ${output_rst}
echo "=======================" >> ${output_rst}
echo "" >> ${output_rst}

for sql_file in `ls *.sql`
do
    echo "converting ${sql_file} to rst-formatted document..."
    sed ${sql_file} -e 's/^/    /g' | \
    sed -e 's/^    -- //g' >> ${output_rst}
    echo "" >> ${output_rst}
    echo "" >> ${output_rst}
done

Now, put all of above scripts into same sphinx-root directory and edit your index.rst for including ${output_rst}. Next, do this:

yaboo@maniac:~/Projects/SqlProject$ sh convert_sql2rst.sh 
converting sample.sql to rst-formatted document...
converting sample2.sql to rst-formatted document...
yaboo@maniac:~/Projects/SqlProject$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.0.7
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] sample                                                
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] sample                                                 
writing additional files... 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, you can get document like this.

latex tips: how to set up UTF-8 latex environment in Ubuntu 10.04LTS/amd64

I show you utf-8 latex installation steps for utf-8 encodings in Ubuntu-10.04 LTS (amd64) 2011/08/07. I am not sure this is the most effective way, but this can work very well on Ubuntu-10.04 LTS ;-) If you through below steps, you can compile utf-8 encoded tex files and also compile sphinx document!! (And..., if you want to convert sphinx document to pdf format and get ExtBabel error when uses "make all-pdf-ja" command, you should also check here)

Step1. install dvipsk-ja (default package is broken at 2011.06.11 JST)

> sudo add-apt-repository ppa:cosmos-door/dvipsk-ja
> sudo aptitude update
> sudo aptitude upgrade
> sudo aptitude install dvipsk-ja

Step2. install packages

> sudo aptitude install texlive texlive-math-extra texlive-latex-extra texlive-latex-extra-doc texlive-fonts-extra texlive-fonts-extra-doc texlive-fonts-recommended texlive-fonts-recommended-doc texlive-formats-extra texlive-latex-recommended texlive-latex-recommended texlive-extra-utils texlive-font-utils texlive-doc-ja ptex-bin jbibtex-bin mendexk okumura-clsfiles latex-cjk-japanese cmap-adobe-japan1 cmap-adobe-japan2 cmap-adobe-cns1 cmap-adobe-gb1 gs-cjk-resource ghostscript xdvik-ja dvi2ps dvi2ps-fontdesc-morisawa5 jmpost latexmk latex-mk pybliographer yatex

Step3. update latex environment

> updmap
> sudo mktexlsr
> sudo updmap-sys
> sudo dpkg-reconfigure ptex-jisfonts
> sudo jisftconfig add

Step4. get iso image of texlive2010 (this includes platex for utf8)

Step5. mount iso image of texlive2010

sudo mount -o loop texlive2010-20100826.iso /mnt3

Step6. install texlive2010

> sudo ./install-tl
...
Enter command: O [options]
Enter command: L [create symlinks in standard directories]
New value for binary directory [/usr/local/bin]: Enter
New value for man directory    [/usr/local/man]: Enter
New value for info directory   [/usr/local/info]: Enter
Enter command: R
Enter command: I
Installing to: /usr/local/texlive/2010
Installing [0001/2133, time/total: ??:??/??:??]: 12many [376k]
Installing [0002/2133, time/total: 00:00/00:00]: 2up [66k]
Installing [0003/2133, time/total: 00:00/00:00]: ANUfinalexam [3k]
Installing [0004/2133, time/total: 00:00/00:00]: AkkTeX [16k]
Installing [0005/2133, time/total: 00:00/00:00]: Asana-Math [433k]
Installing [0006/2133, time/total: 00:00/00:00]: ESIEEcv [137k]
Installing [0007/2133, time/total: 00:01/18:36]: FAQ-en [4943k]
Installing [0008/2133, time/total: 00:01/03:12]: HA-prosper [266k]
Installing [0009/2133, time/total: 00:01/03:03]: IEEEconf [188k]
Installing [0010/2133, time/total: 00:01/02:58]: IEEEtran [1325k]
Installing [0011/2133, time/total: 00:01/02:28]: MemoirChapStyles [669k]
Installing [0012/2133, time/total: 00:02/04:32]: SIstyle [338k]
Installing [0013/2133, time/total: 00:02/04:22]: SIunits [284k]
....
Installing [2129/2133, time/total: 03:33/03:33]: zhmetrics [66k]
Installing [2130/2133, time/total: 03:33/03:33]: zhspacing [165k]
Installing [2131/2133, time/total: 03:33/03:33]: ziffer [3k]
Installing [2132/2133, time/total: 03:33/03:33]: zwgetfdate [242k]
Installing [2133/2133, time/total: 03:33/03:33]: zwpagelayout [520k]
Time used for installing the packages: 03:33
running mktexlsr /usr/local/texlive/2010/texmf-dist /usr/local/texlive/2010/texmf
mktexlsr: Updating /usr/local/texlive/2010/texmf-dist/ls-R...
mktexlsr: Updating /usr/local/texlive/2010/texmf/ls-R...
mktexlsr: Done.
writing fmtutil.cnf data to /usr/local/texlive/2010/texmf-var/web2c/fmtutil.cnf
writing updmap.cfg to /usr/local/texlive/2010/texmf-config/web2c/updmap.cfg
writing language.dat data to /usr/local/texlive/2010/texmf-var/tex/generic/config/language.dat
writing language.def data to /usr/local/texlive/2010/texmf-var/tex/generic/config/language.def
writing language.dat.lua data to /usr/local/texlive/2010/texmf-var/tex/generic/config/language.dat.lua
running mktexlsr /usr/local/texlive/2010/texmf-var
mktexlsr: Updating /usr/local/texlive/2010/texmf-var/ls-R...
mktexlsr: Done.
running updmap-sys...done
re-running mktexlsr /usr/local/texlive/2010/texmf-var
mktexlsr: Updating /usr/local/texlive/2010/texmf-var/ls-R...
mktexlsr: Done.
pre-generating all format files (fmtutil-sys --all), be patient...done
running path adjustment actions
finished with path adjustment actions
running package specific postactions
finished with package specific postactions

 See
   /usr/local/texlive/2010/index.html
 for links to documentation.  The TeX Live web site (http://tug.org/texlive/)
 contains updates and corrections.

 TeX Live is a joint project of the TeX user groups around the world;
 please consider supporting it by joining the group best for you. The
 list of groups is available on the web at http://tug.org/usergroups.html.

 Add /usr/local/texlive/2010/texmf/doc/man to MANPATH, if not dynamically determined.
 Add /usr/local/texlive/2010/texmf/doc/info to INFOPATH.

 Most importantly, add /usr/local/texlive/2010/bin/x86_64-linux
 to your PATH for current and future sessions.

 Welcome to TeX Live!
Logfile: /usr/local/texlive/2010/install-tl.log

Step7. check platex can corporate with utf-8 encoded text (see -kanji=STRING option)

> platex --help
Usage: ptex [option] texfile
     : ptex [option] &format texfile

-fmt=NAME               use NAME instead of program name or %&format.
-halt-on-error          stop processing at the first error
[-no]-file-line-error   disable/enable file:line:error style messages
-ini                    be iniptex.
-interaction=STRING     set interaction mode (STRING=batchmode|nonstopmode|
                          scrollmode|errorstopmode)
-ipc                    send DVI output to a socket as well as the usual
                          output file
-ipc-start              as -ipc, and also start the server at the other end
-jobname=STRING         set the job name to STRING
-kanji=STRING           set Japanese encoding (STRING=euc|jis|sjis|utf8)
-kpathsea-debug=NUMBER  set path searching debugging flags according to
                          the bits of NUMBER
[-no]-mktex=FMT         disable/enable mktexFMT generation (FMT=tex/tfm)
-mltex                  enable MLTeX extensions such as \charsubdef
-output-comment=STRING  use STRING for DVI file comment instead of date
-output-directory=DIR   use DIR as the directory to write files to
[-no]-parse-first-line  disable/enable parsing of the first line of the
                          input file
-progname=STRING        set program (and fmt) name to STRING
-recorder               enable filename recorder
[-no]-shell-escape      disable/enable \write18{SHELL COMMAND}
-src-specials           insert source specials into the DVI file
-src-specials=WHERE     insert source specials in certain places of
                          the DVI file. WHERE is a comma-separated value
                          list: cr display hbox math par parend vbox
-translate-file=TCXNAME use the TCX file TCXNAME
-help                   print this message and exit.
-version                print version information and exit.

Email bug reports to ptex-staff@ml.asciimw.jp.

sphinx tips: sphinx.ext.pngmath plugin

Below is a sample code for checking how sphinx pngmath plugin works. If you ompile below code and check output with browser, you can see TeX like expression is converted to mathematical expression. You need to install dvipng for using pngmath plugin :-)

====================
sphinx.ext.math test
====================

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

.. math:: (a + b)^2 = a^2 + 2ab + b^2

python tips: googley style docstring

I surveyed some comment style in python. One is sphinx style and the other is google style (they are introduced in this site). However sphinx style is suitable for documentation using sphinx, its code legibility is poorer than google style. Below code is commented in google style.

#!/usr/bin/env python                                                           
#                                                                               
# Copyright 2011 Yuki OYABU Inc.                                                
#                                                                               
# Licensed under the Apache License, Version 2.0 (the "License");               
# you may not use this file except in compliance with the License.              
# You may obtain a copy of the License at                                       
#                                                                               
#     http://www.apache.org/licenses/LICENSE-2.0                                
#                                                                               
# Unless required by applicable law or agreed to in writing, software           
# distributed under the License is distributed on an "AS IS" BASIS,             
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.      
# See the License for the specific language governing permissions and           
# limitations under the License.                                                


def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """                                                                         
    Fetches rows from a Bigtable.                                               
                                                                                
    Retrieves rows pertaining to the given keys from the Table instance         
    represented by big_table. Silly things may happen if                        
    oahter_silly_variable is not None.                                          
                                                                                
    Args:                                                                       
        big_table:                                                              
            An open Bigtable Table instance.                                    
        keys:                                                                   
            A sequence of strings representing the key of each table            
            row to fetch.                                                       
        other_silly_variable:                                                   
            Another optional variable, that has a much longer name than         
            the other args, and which does nothing.                             
                                                                                
    Returns:                                                                    
        A dict mapping keys to the corresponding table row data                 
        fetched. Each row is represented as a tuple of strings. For             
        example::                                                               
                                                                                
            {'Serak' : ('Rigel VII', 'Preparer'),                               
             'Zim': ('Irk', 'Invader'),                                         
             'Lrrr': ('Omicron Persei 8', 'Emperor')}                           
                                                                                
        If a key from the keys argument is missing from the dictionary,         
        then that row was not found in the table.                               
                                                                                
    Raises:                                                                     
        IOError:                                                                
            An error occured accessing the bigtable. Table object.              
    """
    pass


class SampleClass(object):
    """                                                                         
    Summary of class here.                                                      
                                                                                
    Longer class information....                                                
    Longer class information....                                                
                                                                                
    Attributes:                                                                 
        likes_spam:                                                             
            A boolean indicating if we like SPAM or not.                        
        eggs:                                                                   
            An integer count of the eggs we have laid.                          
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

shpinx tips: avoid ExtBabel class error for compiling japanese latex

i don't know why below error occurs...

yaboo@sp2:~/DocProject$ make latex
sphinx-build -b latex -d _build/doctrees   . _build/latex
Running Sphinx v1.0.7
loading translations [ja]... done
loading pickled environment... done
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing testProject.tex... index intro code bd sd 
resolving references...
writing... 
Exception occurred:
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.0.7-py2.6.egg/sphinx/writers/latex.py", line 193, in __init__
    babel = ExtBabel(builder.config.language)
TypeError: __init__() takes exactly 3 arguments (2 given)
The full traceback has been saved in /tmp/sphinx-err-q8bibE.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at ,
or report them in the tracker at . Thanks!
make: *** [latex] エラー 1

modify /usr/local/lib/python2.6/dist-packages/Sphinx-1.0.7-py2.6.egg/sphinx/writers/latex.py
(just comment out non-japanese process....)

if builder.config.language:
    self.elements['classoptions'] += ',english,dvipdfm'
    self.elements['babel'] += r'\newcount\pdfoutput\pdfoutput=0'
    self.elements['preamble'] += \
        r'\AtBeginDvi{\special{pdf:tounicode EUC-UCS2}}'
    self.elements['shorthandoff'] = ''
    self.elements['fncychap'] = '\\usepackage[Sonny]{fncychap}'
else:

sphinx tips: sphinx extenstions and configurations

# Abstraction

I installed blockdiag and seqdiag provided by tk0miya.

This post show you how to install and setup *diag tools and autodoc.

# blockdiag and seqdiag installation

- blockdiag installation

sudo easy_install sphinx

sudo easy_install blockdiag
sudo easy_install sphinxcontrib-blockdiag

- seqdiag installation

sudo easy_install seqdiag
sudo easy_install sphinxcontrib-seqdiag

# additional settings into conf.py

# Enabled extensions (blockdiag and seqdiag, autodoc!)
extensions = ['sphinxcontrib.blockdiag','sphinxcontrib.seqdiag','sphinx.ext.autodoc']

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('./codes'))

# configure default autodoc's action
autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance']

# Fontpath for blockdiag (truetype font)
blockdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'
blockdiag_tex_image_format = 'PNG'

# Fontpath for seqdiag (truetype font)
seqdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'
seqdiag_tex_image_format = 'PNG'

sphinx tips: useful links

sphinx is "python documentation generation" tool.
sphinx is one of powerful documentation tool I have ever used.

Here, I list useful link how to use sphinx and reStructuredText.

sphinx

• sphinx official website
• sphinx: html theming support

reStructuredText

• reStructuredText official website
• quick reStructuredText
  
• reStructuredText cheat sheet

reStructuredText add-on

• blockDiag
• how to use autodoc
• autodoc usage introduced by sphinx official website