You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tajo.apache.org by Apache Wiki <wi...@apache.org> on 2014/03/06 08:52:42 UTC
[Tajo Wiki] Update of "HowToWriteUserDocumentations" by HyunsikChoi
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Tajo Wiki" for change notification.
The "HowToWriteUserDocumentations" page has been changed by HyunsikChoi:
https://wiki.apache.org/tajo/HowToWriteUserDocumentations
Comment:
added how to write user documentations
New page:
We use [[http://sphinx-doc.org/|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 [[http://sphinx-doc.org/|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.
* http://sphinx-doc.org/rest.html
If you get accustomed to using markdown, this article would be helpful for you.
* https://gist.github.com/dupuy/1855764
== Generating user documentations form ReStructuredFormat files ==
Simply, you can generate HTML files by 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 follow the command:
{{{
$ make clean singlehtml
}}}
== 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/incubator/tajo/site tajo-site
}}}
Second, update your generated documentation into ${site-root}/docs/${version}.
{{{
$ cp -r target/html/* ${site-root}/docs/${version}.
}}}
Finally, please commit the site page:
{{{
$ svn commit -m "update log message"
}}}