tajo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jihoon Son <jihoon...@apache.org>
Subject Re: [Discussion] Tajo documentation
Date Wed, 05 Mar 2014 09:27:56 GMT
It's awesome!!
Thanks, Hyunsik!

Jihoon


2014-03-05 18:11 GMT+09:00 Hyunsik Choi <hyunsik@apache.org>:

> 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