tajo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hyunsik Choi <hyun...@apache.org>
Subject Re: [Discussion] Tajo documentation
Date Thu, 06 Mar 2014 07:57:16 GMT
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
>> >> >>>>
>> >> >>>
>> >> >>>
>> >>
>> >>
>>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message