You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tajo.apache.org by Henry Saputra <he...@gmail.com> on 2014/03/03 02:08:23 UTC
Re: [Discussion] Tajo documentation
Hi Hyunsik, both using different themes but still using Sphinx ?
- Henry
On Thu, Feb 27, 2014 at 11:59 PM, Hyunsik Choi <hy...@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 <hy...@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 <he...@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 <hy...@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
>>>
>>
>>
Re: [Discussion] Tajo documentation
Posted by Jihoon Son <ji...@apache.org>.
It's awesome!!
Thanks, Hyunsik!
Jihoon
2014-03-05 18:11 GMT+09:00 Hyunsik Choi <hy...@apache.org>:
> 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 <hy...@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 <he...@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 <hy...@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 <hy...@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 <hy...@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
> > >>>>
> > >>>
> > >>>
> >
> >
>
Re: [Discussion] Tajo documentation
Posted by Henry Saputra <he...@gmail.com>.
Thanks Hyunsik, this is helpful
On Wed, Mar 5, 2014 at 11:57 PM, Hyunsik Choi <hy...@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 <hy...@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 <he...@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 <hy...@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 <hy...@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 <he...@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 <hy...@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 <hy...@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
>>> >> >>>>
>>> >> >>>
>>> >> >>>
>>> >>
>>> >>
>>>
>>
>>
Re: [Discussion] Tajo documentation
Posted by Hyunsik Choi <hy...@apache.org>.
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 <hy...@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 <he...@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 <hy...@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 <hy...@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 <he...@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 <hy...@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 <hy...@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
>> >> >>>>
>> >> >>>
>> >> >>>
>> >>
>> >>
>>
>
>
Re: [Discussion] Tajo documentation
Posted by Hyunsik Choi <hy...@apache.org>.
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 <he...@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 <hy...@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 <hy...@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 <he...@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 <hy...@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 <hy...@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 <hy...@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
> >> >>>>
> >> >>>
> >> >>>
> >>
> >>
>
Re: [Discussion] Tajo documentation
Posted by Henry Saputra <he...@gmail.com>.
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 <hy...@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 <hy...@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 <he...@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 <hy...@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 <hy...@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 <hy...@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
>> >>>>
>> >>>
>> >>>
>>
>>
Re: [Discussion] Tajo documentation
Posted by Hyunsik Choi <hy...@apache.org>.
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 <hy...@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 <he...@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 <hy...@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 <hy...@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 <hy...@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
> >>>>
> >>>
> >>>
>
>
Re: [Discussion] Tajo documentation
Posted by Hyunsik Choi <hy...@apache.org>.
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 <he...@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 <hy...@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 <hy...@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 <he...@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 <hy...@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
>>>>
>>>
>>>