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 Thu, 06 Mar 2014 04:33:32 GMT
Sure, I'll add one page into wiki to explain how to write and make the new
doc.

- hyunsik


On Thu, Mar 6, 2014 at 4:19 AM, Henry Saputra <henry.saputra@gmail.com>wrote:

> 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message