Re: [kaffe] DocBook and Maven proposal
Jim Pick wrote: Hi, I'm trying to figure out a good way of integrating better documentation into the project. The first new document I want to check in is Edouard G. Parmelan's Porting Kaffe to a new platform document. It's a good one to start with, since it's already a complete document written up in DocBook, and it's under the GNU Free Documentation License, so we can use it. Yep. Ean should be notified to take it out of the debian package, though, as the GFDL is not DFSG compatible. Then, over time, we can add additional DocBook documents as people create them. We could probably move many of the FAQ documents into more complete documents, eg. user and developer handbooks, etc. Additionally, we want to support generating and shipping Javadoc documentation (probably using gjdoc as our Javadoc implemention). Initially, I was thinking of rolling my own documentation toolchain, and checking that into the kaffe-extras CVS module. That's quite a bit of work though, involving probably a dozen or so external jars from Apache and elsewhere. As an alternative, I just spent much of today playing with Maven, which is an Apache project which puts a whole bunch of project related build, documentation and release tools under one big umbrella build tool. It can be used as a complete Makefile/ant replacement, if a project wants to use it that way. It is smart enough to understand dependencies between projects, and it will download all the needed jar files from a central repository to satisfy build time dependencies, so it can handle pretty complicated toolchain tasks. It's also fairly easy to use, although the documentation is somewhat weak still (it hasn't reached version 1.0 yet). See this site for more info: http://maven.apache.org/ What's nice about it is that the impact on the source tree is minimal, all that is needed is a few files (project.xml, project.properties) to describe the project layout. There is no need to check additional JAR files into CVS or anything ugly like that. They've got tonnes of canned goals that can be used to generate a lot of cool stuff from the source code tree. Another nice thing is that they have lots of recommendations on how to lay things out that don't seem too objectionable (and can be overridden for legacy locations). Initially, I'm proposing to just use Maven to build the DocBook documentation and JavaDocs. We can look at using the additional features later - there's a lot of cool stuff there. It could be used to generate lots of content for the website, for example. In order to forge ahead, I'm going to propose that we create some new directories to hold the documentation: kaffe (top-level) -+- FAQ (existing) +- docs -+- html +- docbook | +- javadoc (not in CVS) | +- others... +- pdf (not in CVS, or tarballs) +- src -- docbook -+- port-kaffe +- other docbook docs... (sorry for the crappy ascii art) I think that's a great idea! I imagine most hand-written documentation will exist as Simplified XML DocBook docs in docs/src/docbook/document-name-dir/* For CVS users, I propose that we have a target that will generate the HTML versions of the Docbook files (maybe not all of them), and we will check those into kaffe/docs/html. I think we should do this, since enough people build Kaffe out of CVS, and they should have easy access to basic documentation. I don't think we should check in other generated documentation, such as the Javadocs, since that can still be retrieved from the website, or built by the users, and I'd like to keep the CVS checkout from getting much more bloated. yep. When we generate the tarballs for release, the make dist target will regenerate those files using Maven. It will also generate the Javadocs, and other things, which will go into the tarball in docs/html/... Is this OK? I'd like to get some feedback before checking these locations into CVS, since CVS isn't nice about deleting directories if we ultimately choose to put the documentation elsewhere. It sounds very good to me. How much of that is possible with kaffe? Ultimately, I think some portion of the Maven toolchain will probably still have to reside in kaffe-extras, in order to make it easy for multiple developers to get set up properly. I imagine that we will probably need to do a lot of tweaks to it to make it suitable for integration with make dist and for generating content for the website (primarily my problem). We could probably push some of our enhancements upstream to Apache. Should I go ahead, and check what I've got in? Yes, please! I'd like to start doing some work on kaffe-extras as well, when 1.1.3 is out. Given thet Graydon published a JUnit wrapper class for mauve, I was thinking about using adding a task to build.xml to download run mauve with kaffe. It's
Re: [kaffe] DocBook and Maven proposal
Michael Franz wrote: Now that I am fooling around with doxygen, I found that it can actually provide some documentation without the special tags. It is actually a good starting point for understanding the API with Kaffe. Once the tags are added, the documentation will make it easier to understand what different methods do. It also understands the JavaDoc tags, so, do we use the C tags or stick with the JavaDoc tags? I'd say use the javadoc tags. I guess the only relevant tag is @param anyway ;) I've seen that one was used by Helmer to add some comments to the core VM. cheers, dalibor topic ___ kaffe mailing list [EMAIL PROTECTED] http://kaffe.org/cgi-bin/mailman/listinfo/kaffe
Re: [kaffe] DocBook and Maven proposal
--- Jim Pick [EMAIL PROTECTED] wrote: Hi, I'm trying to figure out a good way of integrating better documentation into the project. Cool. snip Additionally, we want to support generating and shipping Javadoc documentation (probably using gjdoc as our Javadoc implemention). I have been thinking about this for the past few days, however I am interested in documenting the C code that makes up Kaffe. I am familiar with HeaderDoc from Apple and have been looking at GPL alternatives. I have found Doxygen that seems to be very complete and has been used in a number of projects. http://www.stack.nl/~dimitri/doxygen/ Here is a list of other free source code documentation tools. http://www.stack.nl/~dimitri/doxygen/links.html I took a brief look at gjdoc, but there is only the cvs code. What will be the feature set of gjdoc? Michael __ Do you Yahoo!? Free Pop-Up Blocker - Get it now http://companion.yahoo.com/ ___ kaffe mailing list [EMAIL PROTECTED] http://kaffe.org/cgi-bin/mailman/listinfo/kaffe
Re: [kaffe] DocBook and Maven proposal
On Sun, 30 Nov 2003 08:10:43 -0800 (PST) Michael Franz [EMAIL PROTECTED] wrote: I have been thinking about this for the past few days, however I am interested in documenting the C code that makes up Kaffe. I am familiar with HeaderDoc from Apple and have been looking at GPL alternatives. I have found Doxygen that seems to be very complete and has been used in a number of projects. http://www.stack.nl/~dimitri/doxygen/ Here is a list of other free source code documentation tools. http://www.stack.nl/~dimitri/doxygen/links.html I haven't played with it yet, but Doxygen is extremely popular -- I know we use it at the place I work. I think that would be a safe one to go with. I'm encouraged that there also seems to be a Maven plugin for it: http://maven-plugins.sf.net/maven-doxygen-plugin/ So, theoretically, we can plug it into our Maven-based documentation generation system. Again, I expect that we may have to modify a few Maven plugins and put them in kaffe-extras to get the exact output we want for the published tarballs and the website. I took a brief look at gjdoc, but there is only the cvs code. What will be the feature set of gjdoc? I'll have to let someone else answer that, as I haven't played with it yet. I'm hoping it's got the basic Javadoc features so that we use it as our Javadoc, and use it with tools such as Ant and Maven. I think some IDEs parse the generated HTML documentation, so that might be one tricky area for compatibility to watch out for. One more thing I forgot to mention in the proposal - some ideas I have for the documentation development process: 1) I want to keep as much development on the mailing list as possible. 2) I'm thinking of moving the website over to Tomcat - so we can add various webapps to it to do some interesting things. 3) I've got a half-done regression testing system I would like to deploy on the website. I'd like to hook that into the documentation generation system somehow -- primarily so that the documentation can say things like Application XYZ version 1.2.3 passed basic regression tests on Platform XX with Kaffe x.y.z. If we can say things like that, then we'll get users for our future production releases. 4) Even though I want all the discussion to happen on-list, I'm starting to think that a Wiki might be useful. It could be used to store various bits of quickly mutating information, or for editing drafts of half-baked documentation before we commit it into CVS. Opinions? Anyways, I've got too many ideas - it's slowing me down. :-) Cheers, - Jim ___ kaffe mailing list [EMAIL PROTECTED] http://kaffe.org/cgi-bin/mailman/listinfo/kaffe
Re: [kaffe] DocBook and Maven proposal
Michael Franz wrote: I haven't played with it yet, but Doxygen is extremely popular -- I know we use it at the place I work. I think that would be a safe one to go with. I'm encouraged that there also seems to be a Maven plugin for it: http://maven-plugins.sf.net/maven-doxygen-plugin/ So, theoretically, we can plug it into our Maven-based documentation generation system. Again, I expect that we may have to modify a few Maven plugins and put them in kaffe-extras to get the exact output we want for the published tarballs and the website. Ok, I will start to document the stuff I am interested in using Doxygen. If the Kaffe developers start to use it, then I will be ahead of the game, otherwise, I will still benefit from it. Yeah, using doxygen makes a lot of sense. I'm using doxygen comments on things I fix/change in the C files as well. cheers, dalibor topic ___ kaffe mailing list [EMAIL PROTECTED] http://kaffe.org/cgi-bin/mailman/listinfo/kaffe
Re: [kaffe] DocBook and Maven proposal
Now that I am fooling around with doxygen, I found that it can actually provide some documentation without the special tags. It is actually a good starting point for understanding the API with Kaffe. Once the tags are added, the documentation will make it easier to understand what different methods do. It also understands the JavaDoc tags, so, do we use the C tags or stick with the JavaDoc tags? Yeah, using doxygen makes a lot of sense. I'm using doxygen comments on things I fix/change in the C files as well. cheers, dalibor topic Michael __ Do you Yahoo!? Free Pop-Up Blocker - Get it now http://companion.yahoo.com/ ___ kaffe mailing list [EMAIL PROTECTED] http://kaffe.org/cgi-bin/mailman/listinfo/kaffe
