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, 26 Feb 2014 23:31:43 GMT
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