Hi guys, I've added HowToWriteUserDocumentations ( https://wiki.apache.org/tajo/HowToWriteUserDocumentations) in Tajo wiki. I hope that it would be helpful for you guys.
- hyunsik On Thu, Mar 6, 2014 at 1:33 PM, Hyunsik Choi <[email protected]> wrote: > 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 <[email protected]>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 <[email protected]> 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 <[email protected]> >> 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 <[email protected]> >> >> wrote: >> >> >> >> > 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 >> >> >>>> >> >> >>> >> >> >>> >> >> >> >> >> > >
