tajo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Henry Saputra <henry.sapu...@gmail.com>
Subject Re: [Discussion] Tajo documentation
Date Fri, 07 Mar 2014 06:38:12 GMT
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
>>> >> >>>>
>>> >> >>>
>>> >> >>>
>>> >>
>>> >>
>>>
>>
>>

Mime
View raw message