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 <[email protected]>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 <[email protected]> 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 >
