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