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:
- Sophisticated markup features.
- Multiple outputs (PDF, multiple page HTML, and single page HTML) from a single document source.
- One documentation generated from multiple pages
- Better look
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
Prerequisites
You should prepare the followings:
- sphinx
- pip
- sphinx-rtd-theme (theme we used)
$ 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
FAQ
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 mercurial.util.set_binary(fp) File "/opt/local/lib/python2.5/site-packages/mercurial/demandimport.py", line 75, in __getattribute__ self._load() 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"