We use Sphinx for user documentations. This page explains how to write and how to update user documentaions.

Why we use Sphinx

We discussed the documention tool change at http://markmail.org/thread/5mopd5mjh3vavy7t.

Briefly, the advantages of Sphinx are as follows:

How to write user documentations

Sphinx supports reStructuredText format. So, you should use reStructuredText semantic for all user documentations. reStructuredText semantic is somewhat similar to wiki semantic and markdown. But, it is more sophisticated and has more richful features.

If you want to learn reStructuredText format, please refer the following references.

If you get accustomed to using markdown, this article would be helpful for you.

Generating user documentations form ReStructuredFormat files


You should prepare the followings:

 $ sudo easy_install sphinx
 $ sudo easy_install pip
 $ sudo pip install sphinx_rtd_theme

Generating documentations

Then, you can generate HTML files with make utility as follow.

  $ cd tajo-docs
  $ make clean html

In addition, ReStructuredFormat supports the following output formats.

[hyunsik@hostname tajo-docs]$ make
Please use `make <target>' where <target> is one of
  html       to make standalone HTML files
  dirhtml    to make HTML files named index.html in directories
  singlehtml to make a single large HTML file
  pickle     to make pickle files
  json       to make JSON files
  htmlhelp   to make HTML files and a HTML help project
  qthelp     to make HTML files and a qthelp project
  devhelp    to make HTML files and a Devhelp project
  epub       to make an epub
  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  latexpdf   to make LaTeX files and run them through pdflatex
  latexpdfja to make LaTeX files and run them through platex/dvipdfmx
  text       to make text files
  man        to make manual pages
  texinfo    to make Texinfo files
  info       to make Texinfo files and run them through makeinfo
  gettext    to make PO message catalogs
  changes    to make an overview of all changed/added/deprecated items
  xml        to make Docutils-native XML files
  pseudoxml  to make pseudoxml-XML files for display purposes
  linkcheck  to check all external links for integrity
  doctest    to run all doctests embedded in the documentation (if enabled)

For example, if you want to generate a single html file, please execute the command.

$ make clean singlehtml


ValueError: unknown locale: UTF-8

You can meet ValueError: unknown locale: UTF-8 error especially in Mac OS X.

Traceback (most recent call last):
File "/opt/local/bin/hg", line 25, in 
File "/opt/local/lib/python2.5/site-packages/mercurial/demandimport.py", line 75, in __getattribute__
File "/opt/local/lib/python2.5/site-packages/mercurial/demandimport.py", line 47, in _load
mod = _origimport(head, globals, locals)
File "/opt/local/lib/python2.5/site-packages/mercurial/util.py", line 93, in 
_encoding = locale.getlocale()[1]
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/locale.py", line 462, in getlocale
return _parse_localename(localename)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/locale.py", line 375, in _parse_localename
raise ValueError, 'unknown locale: %s' % localename
ValueError: unknown locale: UTF-8

In order to solve the problem, you should set two environment variables in your ${HOME}/.profile or ${HOME}/.bashrc.

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

How to update user documentations in Tajo site

Note that this update is only available for Tajo PMC and committers.

Firstly, please check out Tajo site's svn repo.

$ svn co https://svn.apache.org/repos/asf/tajo/site tajo-site

Second, update your generated documentation into ${site-root}/docs/${version}.

$ cp -r target/html/* ${site-root}/docs/${version}.

Then, please commit the site page.

$ svn commit -m "update log message"

See Also

HowToWriteUserDocumentations (last edited 2014-03-25 06:14:38 by JihoonSon)