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 Wed, 05 Mar 2014 19:19:25 GMT
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