Hi Hyunsik, both using different themes but still using Sphinx ? - Henry
On Thu, Feb 27, 2014 at 11:59 PM, Hyunsik Choi <[email protected]> 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 <[email protected]> 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 >> <[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 >>> >> >>
