|Hyunsik Choi||Feb 24, 2014 9:22 pm|
|Jinho Kim||Feb 26, 2014 12:05 am|
|Hyunsik Choi||Feb 26, 2014 5:25 am|
|Henry Saputra||Feb 26, 2014 3:31 pm|
|ktpark||Feb 26, 2014 5:52 pm|
|ktpark||Feb 26, 2014 6:11 pm|
|Jakob Homan||Feb 26, 2014 6:29 pm|
|Henry Saputra||Feb 26, 2014 7:00 pm|
|ktpark||Feb 26, 2014 9:44 pm|
|CharSyam||Feb 26, 2014 10:38 pm|
|Hyunsik Choi||Feb 27, 2014 11:58 pm|
|Eli Reisman||Mar 2, 2014 8:39 pm|
|Hyunsik Choi||Mar 5, 2014 1:10 am|
|Jihoon Son||Mar 5, 2014 1:27 am|
|Henry Saputra||Mar 5, 2014 11:19 am|
|Henry Saputra||Mar 6, 2014 10:37 pm|
|Subject:||Re: [Discussion] Tajo documentation|
|From:||Hyunsik Choi (hyun...@apache.org)|
|Date:||Feb 27, 2014 11:58:51 pm|
I've created TAJO-642 issue. Please take a look at the candidate documentations:
Best regards, Hyunsik
On Thu, Feb 27, 2014 at 8:58 AM, Hyunsik Choi <hyun...@apache.org> wrote:
You can see lots of examples at http://sphinx-doc.org/examples.html.
I think that we will mostly make user documentations with Sphinx. Sphinx uses pygments for syntax highlighting. It supports a variety of languages as you can see http://pygments.org/languages/. So, there is no language dependent problem. In addition, developer documentation would be sufficient with javadoc and wiki.
Yes, I have a plan to change a single user documentation md file ( http://tajo.incubator.apache.org/tajo-0.8.0-doc.html) into RST format of Sphinx. As you can see, I have faced many problems aforementioned while I'm making the documentation. I believe that Sphinx will solve these problems.
On Thu, Feb 27, 2014 at 8:31 AM, Henry Saputra <henr...@gmail.com>wrote:
Sorry for the late reply Hyunsik.
I have never used Sphinx before but quick glance from the website I thought it is primarily used to document Python code?
Is the plan to move all md files for Tajo doc into bunch of Sphinx files?
Looks like Pandoc  can help covert md files into Sphinx code.
On Mon, Feb 24, 2014 at 9:23 PM, Hyunsik Choi <hyun...@apache.org> wrote:
I would like to discuss the choice of documentation tool. Currently, we have used markdown and generated single page HTML document from the markdown via maven-site-plugin.
I think that this approach has several problems as follows: * a single page is very inconvenience to edit documents. I should have frequently scrolled a long page. * The generated html from markdown page does not support table of contents. The table of contents in the current doc has been manually written by hand. * It is hard to output multiple doc formats from single source.
According to the characteristics of our project, we should maintain lots of documentations. I think that it is very important to choose the proper documentation tool before too late.
I've found open source documentation tools for Tajo. I would like to propose using sphinx (http://sphinx-doc.org) for our documentation tool. It seems to meet our needs.
If you know other nice doc tools, feel free to suggest.
Best regards, Hyunsik Choi