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 Fri, 28 Feb 2014 07:59:14 GMT
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