atom feed28 messages in org.apache.tajo.devRe: [Discussion] Tajo documentation
FromSent OnAttachments
Hyunsik ChoiFeb 24, 2014 9:22 pm 
Jihoon SonFeb 25, 2014 10:39 pm 
JaeHwa JungFeb 25, 2014 10:45 pm 
Jinho KimFeb 26, 2014 12:05 am 
Hyunsik ChoiFeb 26, 2014 5:25 am 
Henry SaputraFeb 26, 2014 3:31 pm 
Hyunsik ChoiFeb 26, 2014 3:57 pm 
ktparkFeb 26, 2014 5:29 pm 
Jihoon SonFeb 26, 2014 5:46 pm 
ktparkFeb 26, 2014 5:52 pm 
JaeHwa JungFeb 26, 2014 6:03 pm 
ktparkFeb 26, 2014 6:11 pm 
Jinho KimFeb 26, 2014 6:18 pm 
Hyunsik ChoiFeb 26, 2014 6:26 pm 
Jakob HomanFeb 26, 2014 6:29 pm 
Henry SaputraFeb 26, 2014 7:00 pm 
ktparkFeb 26, 2014 9:44 pm 
CharSyamFeb 26, 2014 10:38 pm 
Hyunsik ChoiFeb 27, 2014 11:58 pm 
Henry SaputraMar 2, 2014 5:08 pm 
Hyunsik ChoiMar 2, 2014 5:31 pm 
Eli ReismanMar 2, 2014 8:39 pm 
Hyunsik ChoiMar 5, 2014 1:10 am 
Jihoon SonMar 5, 2014 1:27 am 
Henry SaputraMar 5, 2014 11:19 am 
Hyunsik ChoiMar 5, 2014 8:33 pm 
Hyunsik ChoiMar 5, 2014 11:56 pm 
Henry SaputraMar 6, 2014 10:37 pm 
Subject:Re: [Discussion] Tajo documentation
From:Hyunsik Choi (hyun@apache.org)
Date:Feb 27, 2014 11:58:51 pm
List:org.apache.tajo.dev

I've created TAJO-642 issue. Please take a look at the candidate documentations:

http://people.apache.org/~hyunsik/new_docs/ http://people.apache.org/~hyunsik/rtd/

Best regards, Hyunsik

Hi Henry,

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.

Thanks, Hyunsik

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 [1] can help covert md files into Sphinx code.

- Henry

[1] http://johnmacfarlane.net/pandoc/

On Mon, Feb 24, 2014 at 9:23 PM, Hyunsik Choi <hyun@apache.org> wrote:

Hi folks,

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.