Mailing-List: contact dev-help@tajo.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@tajo.incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of henry.saputra@gmail.com
 designates 74.125.82.49 as permitted sender)
MIME-Version: 1.0
In-Reply-To: 
 <CAM=XDd96-5VD_nji=v4PEAZtsYTo0A_N_Ns3-1qM8kYxACMU3w@mail.gmail.com>
References: 
 <CAM=XDd-+7UawWW8YtKWV=B-VXTnUp9-8Z8MoXmppJgcEvdoKUA@mail.gmail.com>
	<CALuGr6ZuW3upSvipdvssPqMciW24_5SUyzArSXgW-_avjdR_VA@mail.gmail.com>
	<CAM=XDd94anH-zahK4xe43LTax-ZSHTrRA9o1_5p76dj62UxrAA@mail.gmail.com>
	<CAM=XDd89Y6eUFu8r5i8oP=cS2QyrYgY9WuGSM47JivA4W=OvEA@mail.gmail.com>
	<CALuGr6Y54zZv06sZTjG_J1X2J6pc38PAaJJbwAPrfRM0By9faA@mail.gmail.com>
	<D85CB3C4-79E5-4EA5-8AC1-5671FEF0144A@apache.org>
	<CAM=XDd9q+6fFrRg5r8JUgxHLimUz9jNkaRV_DKY_VCVgs9Lrcw@mail.gmail.com>
	<CALuGr6a+Y6T4W+d4w-JzuqkDFMM7KkkoOkQAKgUgU0eiV9aNJA@mail.gmail.com>
	<CAM=XDd9PRRouUxOhcHF4Nt0ZL2CiUrPAVB8i0dX+oWyZ+2NQRw@mail.gmail.com>
	<CAM=XDd96-5VD_nji=v4PEAZtsYTo0A_N_Ns3-1qM8kYxACMU3w@mail.gmail.com>
Date: Thu, 6 Mar 2014 22:38:12 -0800
Message-ID: 
 <CALuGr6YTOMa_F7cSUrg+-80KzAYn5x9fqQLP2SOb9pLLb8CpbA@mail.gmail.com>
Subject: Re: [Discussion] Tajo documentation
From: Henry Saputra <henry.saputra@gmail.com>
To: "dev@tajo.incubator.apache.org" <dev@tajo.incubator.apache.org>
Content-Type: text/plain; charset=UTF-8

Thanks Hyunsik, this is helpful

On Wed, Mar 5, 2014 at 11:57 PM, Hyunsik Choi <hyunsik@apache.org> wrote:
> Hi guys,
>
> I've added HowToWriteUserDocumentations (
> https://wiki.apache.org/tajo/HowToWriteUserDocumentations) in Tajo wiki.
> I hope that it would be helpful for you guys.
>
> - hyunsik
>
>
> On Thu, Mar 6, 2014 at 1:33 PM, Hyunsik Choi <hyunsik@apache.org> wrote:
>
>> Sure, I'll add one page into wiki to explain how to write and make the new
>> doc.
>>
>> - hyunsik
>>
>>
>> On Thu, Mar 6, 2014 at 4:19 AM, Henry Saputra <henry.saputra@gmail.com>wrote:
>>
>>> W00t!
>>>
>>> Do you have any wiki or info on how to update the new doc?
>>>
>>> - Henry
>>>
>>> On Wed, Mar 5, 2014 at 1:11 AM, Hyunsik Choi <hyunsik@apache.org> wrote:
>>> > The user documentation has been updated at
>>> > http://tajo.incubator.apache.org/docs/0.8.0/index.html.
>>> >
>>> > As you can see, there are many missed docs. In order to add more
>>> documents,
>>> > I've created the jira issue (
>>> https://issues.apache.org/jira/browse/TAJO-658).
>>> > If there are any volunteers, feel free to assign the issue or create
>>> more
>>> > jira issues.
>>> >
>>> > Best regards,
>>> > Hyunsik Choi
>>> >
>>> >
>>> >
>>> > On Mon, Mar 3, 2014 at 10:31 AM, Hyunsik Choi <hyunsik@apache.org>
>>> wrote:
>>> >
>>> >> I missed to mention that; I mentioned only in Jira.
>>> >> Yes, they are just different themes.
>>> >>
>>> >> - hyunsik
>>> >>
>>> >>
>>> >> On Mar 3, 2014, at 10:08 AM, Henry Saputra <henry.saputra@gmail.com>
>>> >> wrote:
>>> >>
>>> >> > Hi Hyunsik, both using different themes but still using Sphinx ?
>>> >> >
>>> >> > - Henry
>>> >> >
>>> >> > On Thu, Feb 27, 2014 at 11:59 PM, Hyunsik Choi <hyunsik@apache.org>
>>> >> wrote:
>>> >> >> 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
>>> >> >>
>>> >> >>
>>> >> >> On Thu, Feb 27, 2014 at 8:58 AM, Hyunsik Choi <hyunsik@apache.org>
>>> >> wrote:
>>> >> >>
>>> >> >>> 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 <
>>> >> henry.saputra@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 <hyunsik@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.
>>> >> >>>>>
>>> >> >>>>> Best regards,
>>> >> >>>>> Hyunsik Choi
>>> >> >>>>
>>> >> >>>
>>> >> >>>
>>> >>
>>> >>
>>>
>>
>>