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 Mon, 03 Mar 2014 01:08:23 GMT
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