Re: Javadoc management
My involvement was with what has now become tucked away in a zip file called alexandria-legacy. At this time Alexandria was an ant build script with some ant extensions. Most of these are now part of ant. Alexandra's main goal was to allow people to access javadoc and xrefed source code. The build and testing stuff was just a logical extension of having a system which could automatically checkout code. Gump now handles this much better. Anyway just trying to bring people's attention to an existing solution rather than trying to start everything from scratch. On Fri, 2005-03-18 at 12:22 -0500, Henri Yandell wrote: > My negatives for Alexandria: > > * Seems large and yet dead > * Has lofty goals, whereas the below is very basic > > Gump is another possibility. I noticed the other day that they have > javadoc in the gump.xml. > > My argument for the below over trying to do things with gump is that it is > simple to get running and find out what we actually want. Once we have > that, we can try to drive gump/alexandria/something-else. > > Hen > > On Fri, 18 Mar 2005, Jeff Martin wrote: > > > Just wondering if anyone had looked at Alexandria. > > http://jakarta.apache.org/alexandria/legacy/ > > > > On Fri, 2005-03-18 at 00:31 -0500, Henri Yandell wrote: > >> > >> On Thu, 17 Mar 2005, J Aaron Farr wrote: > >> > >>> On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell > >>> <[EMAIL PROTECTED]> wrote: > > Interested in finding out if anyone else thinks this would be a good > idea. > > Rather than have each subproject managing their release javadocs > separately, I think it would be good if we treated the javadoc more like > the releases. Located in a central location, perhaps mirrored, all > versions available and perhaps with additional tools like ashkelon or > multidoc to bring them together. > >>> > >>> I guess I'm hoping for something like: > >>> > >>> http://api.apache.org/$group/$artifact/$version/ > >> > >> Sounds good, though possibly: > >> > >> http://jakarta.apache.org/api/$subproject/$artifact/$version/ > >> > >> to get a prototype up and running. > >> > >>> with features like > >>> > >>> * download the javadocs > >> > >> +1. Unsure how this would balance with the download pages. > >> > >>> * search javadocs > >> > >> +1 long-term. > >> > >>> * have javadocs linked to source reference (so maybe have an 'api' > >>> and a 'src' directory) > >> > >> Not hugely essential I think. > >> > >>> * have javadocs linked to each other > >> > >> Would be very nice, but seems like a battle. We wouldn't want to rebuild > >> the javadoc as part of this, and might not be easy to find a way to munge > >> existing javadoc to point to each other. Also means dependency knowledge, > >> which version of Collections did this BeanUtils use. > >> > >>> * include test and taglib javadocs > >> > >> +1 on taglibs. Test ones are less essential to start with I think. > >> > >>> Plus it's got to be pretty simple to set this up or for projects to > >>> contribute to it. > >> > >> To start with, I'm generally thinking of a defined file structure in which > >> unzipped javadocs appear, a location for downloadable javadoc to be and a > >> front end to make it easy to get to the relevant javadoc. > >> > >> A release would involve putting the new javadoc in place, adding it to the > >> front-end (hopefully in a one-line kind of way) and then creating a > >> downloadable zip. > >> > >> Initial plan would be to propose a structure for the repository (I like > >> yours), go extract a lot of javadocs from our downloads to seed the > >> repository, and come up with a simple-front-end to let people use them. > >> > >> An important requirement will be the need for a subproject/group to be > >> able to link to a page that defines their javadoc, rather than at the top > >> level. > >> > >> Hen > >> > >> - > >> To unsubscribe, e-mail: [EMAIL PROTECTED] > >> For additional commands, e-mail: [EMAIL PROTECTED] > > -- > > Jeff Martin > > > > Memetic Engineer > > > > http://www.custommonkey.org/ > > > > > > > > > > - > > To unsubscribe, e-mail: [EMAIL PROTECTED] > > For additional commands, e-mail: [EMAIL PROTECTED] > > > > - > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] -- jeff martin information technologist mkodo limited mobile: 44 (0) 78 55 478 331 phone: 44 (0) 20 77 29 45 45 email: [EMAIL PROTECTED] www.mkodo.com 73 Leonard St, London, EC2A 4QS. U.K - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
On Fri, 18 Mar 2005, J Aaron Farr wrote: On Fri, 18 Mar 2005 12:22:35 -0500 (EST), Henri Yandell <[EMAIL PROTECTED]> wrote: Gump is another possibility. I noticed the other day that they have javadoc in the gump.xml. Trouble with having this Gump driven is that Gump is all about building the latest snapshot, not about building a specific release version. Moreover, the builds have a pretty high failure rate. Right. But that does bring up a good question about where the javadocs come from. Would this site/tool generate them directly from the source or would projects have to supply the javadocs? If projects have to supply the pre-generated Javadocs then we could just require they are distributed via the mirrors and this site could pick them up from there. First I was thinking that it would be this way. We'd effectively get a working prototype of how things can look and user's can find javadocs a lot more easily, without us having to try and guess what a more complex system would look like. The only pain created would be as an addition to release management, which is annoying as release management is already a slow enough process, but we're going to be tying this to releases no matter what happens anyway. However, if the site generates the javadocs then we'd have a lot more control over how they look and how they're linked. Then I would see us discussing this. It could involve loading into ashkelon etc. We'd have a basic working system to use as a foundation to all the ideas. Hen - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
On Fri, 18 Mar 2005 12:22:35 -0500 (EST), Henri Yandell <[EMAIL PROTECTED]> wrote: > Gump is another possibility. I noticed the other day that they have > javadoc in the gump.xml. Trouble with having this Gump driven is that Gump is all about building the latest snapshot, not about building a specific release version. Moreover, the builds have a pretty high failure rate. But that does bring up a good question about where the javadocs come from. Would this site/tool generate them directly from the source or would projects have to supply the javadocs? If projects have to supply the pre-generated Javadocs then we could just require they are distributed via the mirrors and this site could pick them up from there. However, if the site generates the javadocs then we'd have a lot more control over how they look and how they're linked. -- jaaron - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
My negatives for Alexandria: * Seems large and yet dead * Has lofty goals, whereas the below is very basic Gump is another possibility. I noticed the other day that they have javadoc in the gump.xml. My argument for the below over trying to do things with gump is that it is simple to get running and find out what we actually want. Once we have that, we can try to drive gump/alexandria/something-else. Hen On Fri, 18 Mar 2005, Jeff Martin wrote: Just wondering if anyone had looked at Alexandria. http://jakarta.apache.org/alexandria/legacy/ On Fri, 2005-03-18 at 00:31 -0500, Henri Yandell wrote: On Thu, 17 Mar 2005, J Aaron Farr wrote: On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell <[EMAIL PROTECTED]> wrote: Interested in finding out if anyone else thinks this would be a good idea. Rather than have each subproject managing their release javadocs separately, I think it would be good if we treated the javadoc more like the releases. Located in a central location, perhaps mirrored, all versions available and perhaps with additional tools like ashkelon or multidoc to bring them together. I guess I'm hoping for something like: http://api.apache.org/$group/$artifact/$version/ Sounds good, though possibly: http://jakarta.apache.org/api/$subproject/$artifact/$version/ to get a prototype up and running. with features like * download the javadocs +1. Unsure how this would balance with the download pages. * search javadocs +1 long-term. * have javadocs linked to source reference (so maybe have an 'api' and a 'src' directory) Not hugely essential I think. * have javadocs linked to each other Would be very nice, but seems like a battle. We wouldn't want to rebuild the javadoc as part of this, and might not be easy to find a way to munge existing javadoc to point to each other. Also means dependency knowledge, which version of Collections did this BeanUtils use. * include test and taglib javadocs +1 on taglibs. Test ones are less essential to start with I think. Plus it's got to be pretty simple to set this up or for projects to contribute to it. To start with, I'm generally thinking of a defined file structure in which unzipped javadocs appear, a location for downloadable javadoc to be and a front end to make it easy to get to the relevant javadoc. A release would involve putting the new javadoc in place, adding it to the front-end (hopefully in a one-line kind of way) and then creating a downloadable zip. Initial plan would be to propose a structure for the repository (I like yours), go extract a lot of javadocs from our downloads to seed the repository, and come up with a simple-front-end to let people use them. An important requirement will be the need for a subproject/group to be able to link to a page that defines their javadoc, rather than at the top level. Hen - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] -- Jeff Martin Memetic Engineer http://www.custommonkey.org/ - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
Just wondering if anyone had looked at Alexandria. http://jakarta.apache.org/alexandria/legacy/ On Fri, 2005-03-18 at 00:31 -0500, Henri Yandell wrote: > > On Thu, 17 Mar 2005, J Aaron Farr wrote: > > > On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell > > <[EMAIL PROTECTED]> wrote: > >> > >> Interested in finding out if anyone else thinks this would be a good idea. > >> > >> Rather than have each subproject managing their release javadocs > >> separately, I think it would be good if we treated the javadoc more like > >> the releases. Located in a central location, perhaps mirrored, all > >> versions available and perhaps with additional tools like ashkelon or > >> multidoc to bring them together. > > > > I guess I'm hoping for something like: > > > > http://api.apache.org/$group/$artifact/$version/ > > Sounds good, though possibly: > > http://jakarta.apache.org/api/$subproject/$artifact/$version/ > > to get a prototype up and running. > > > with features like > > > > * download the javadocs > > +1. Unsure how this would balance with the download pages. > > > * search javadocs > > +1 long-term. > > > * have javadocs linked to source reference (so maybe have an 'api' > > and a 'src' directory) > > Not hugely essential I think. > > > * have javadocs linked to each other > > Would be very nice, but seems like a battle. We wouldn't want to rebuild > the javadoc as part of this, and might not be easy to find a way to munge > existing javadoc to point to each other. Also means dependency knowledge, > which version of Collections did this BeanUtils use. > > > * include test and taglib javadocs > > +1 on taglibs. Test ones are less essential to start with I think. > > > Plus it's got to be pretty simple to set this up or for projects to > > contribute to it. > > To start with, I'm generally thinking of a defined file structure in which > unzipped javadocs appear, a location for downloadable javadoc to be and a > front end to make it easy to get to the relevant javadoc. > > A release would involve putting the new javadoc in place, adding it to the > front-end (hopefully in a one-line kind of way) and then creating a > downloadable zip. > > Initial plan would be to propose a structure for the repository (I like > yours), go extract a lot of javadocs from our downloads to seed the > repository, and come up with a simple-front-end to let people use them. > > An important requirement will be the need for a subproject/group to be > able to link to a page that defines their javadoc, rather than at the top > level. > > Hen > > - > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] -- Jeff Martin Memetic Engineer http://www.custommonkey.org/ - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
On Thu, 17 Mar 2005, J Aaron Farr wrote: On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell <[EMAIL PROTECTED]> wrote: Interested in finding out if anyone else thinks this would be a good idea. Rather than have each subproject managing their release javadocs separately, I think it would be good if we treated the javadoc more like the releases. Located in a central location, perhaps mirrored, all versions available and perhaps with additional tools like ashkelon or multidoc to bring them together. I guess I'm hoping for something like: http://api.apache.org/$group/$artifact/$version/ Sounds good, though possibly: http://jakarta.apache.org/api/$subproject/$artifact/$version/ to get a prototype up and running. with features like * download the javadocs +1. Unsure how this would balance with the download pages. * search javadocs +1 long-term. * have javadocs linked to source reference (so maybe have an 'api' and a 'src' directory) Not hugely essential I think. * have javadocs linked to each other Would be very nice, but seems like a battle. We wouldn't want to rebuild the javadoc as part of this, and might not be easy to find a way to munge existing javadoc to point to each other. Also means dependency knowledge, which version of Collections did this BeanUtils use. * include test and taglib javadocs +1 on taglibs. Test ones are less essential to start with I think. Plus it's got to be pretty simple to set this up or for projects to contribute to it. To start with, I'm generally thinking of a defined file structure in which unzipped javadocs appear, a location for downloadable javadoc to be and a front end to make it easy to get to the relevant javadoc. A release would involve putting the new javadoc in place, adding it to the front-end (hopefully in a one-line kind of way) and then creating a downloadable zip. Initial plan would be to propose a structure for the repository (I like yours), go extract a lot of javadocs from our downloads to seed the repository, and come up with a simple-front-end to let people use them. An important requirement will be the need for a subproject/group to be able to link to a page that defines their javadoc, rather than at the top level. Hen - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell <[EMAIL PROTECTED]> wrote: > > Interested in finding out if anyone else thinks this would be a good idea. > > Rather than have each subproject managing their release javadocs > separately, I think it would be good if we treated the javadoc more like > the releases. Located in a central location, perhaps mirrored, all > versions available and perhaps with additional tools like ashkelon or > multidoc to bring them together. I guess I'm hoping for something like: http://api.apache.org/$group/$artifact/$version/ with features like * download the javadocs * search javadocs * have javadocs linked to source reference (so maybe have an 'api' and a 'src' directory) * have javadocs linked to each other * include test and taglib javadocs Plus it's got to be pretty simple to set this up or for projects to contribute to it. I like the idea of including javadocs as part of the release process and I like the idea of encouraging projects to host the lastest javadocs on their own site. -- jaaron - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
At 12:49 AM -0500 3/16/05, Henri Yandell wrote: (though seeing a tag doc in javadoc style would rock). Have you seen https://taglibrarydoc.dev.java.net/ It is used, for example, to generate this: http://java.sun.com/products/jsp/jstl/1.1/docs/tlddocs/ There's a Maven plugin which is savvy about this tool, but I haven't used it: http://maven-taglib.sourceforge.net/index.html Joe -- Joe Germuska [EMAIL PROTECTED] http://blog.germuska.com "Narrow minds are weapons made for mass destruction" -The Ex - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
On Tue, 15 Mar 2005, Martin Cooper wrote: On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell <[EMAIL PROTECTED]> wrote: Interested in finding out if anyone else thinks this would be a good idea. Rather than have each subproject managing their release javadocs separately, I think it would be good if we treated the javadoc more like the releases. Located in a central location, perhaps mirrored, all versions available and perhaps with additional tools like ashkelon or multidoc to bring them together. Sounds good to me (assuming you mean all *released* versions available). On download pages, we could have binaries, sources and javadocs, with options for javadocs being download or view online (a bit like Sun's download pages). We might not need to mirror right away - we could wait to see how much this gets used. Yep. Unsure if the download page would be the best place for the view online option though. I'm not familiar with ashkelon or multidoc. What would they bring to the party? Ashkelon is an alternative to javadoc really. You load the javadoc into a database and it gives you a searchable system and a slightly more descriptive version of javadoc. I've a basic version running at: http://issues.osjava.org/ashkelon/apis.do while http://www.jdocs.com/ have a more customised version. It requires a db and a tomcat server. Multidocs is a hack of mine. It scrapes from various existing javadoc urls and builds a wrapper around them: http://www.apache.org/~bayard/multidoc/commons-multidoc/ I also had it doing src xref, test coverage etc. Low cost, but all it really adds is a nicer way for the user to find the javadoc they want. Hen - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc management
On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell <[EMAIL PROTECTED]> wrote: > > Interested in finding out if anyone else thinks this would be a good idea. > > Rather than have each subproject managing their release javadocs > separately, I think it would be good if we treated the javadoc more like > the releases. Located in a central location, perhaps mirrored, all > versions available and perhaps with additional tools like ashkelon or > multidoc to bring them together. Sounds good to me (assuming you mean all *released* versions available). On download pages, we could have binaries, sources and javadocs, with options for javadocs being download or view online (a bit like Sun's download pages). We might not need to mirror right away - we could wait to see how much this gets used. I'm not familiar with ashkelon or multidoc. What would they bring to the party? -- Martin Cooper > Subprojects would still be hosting their latest cvs head javadocs > internally, but they would deploy a versioned javadoc as a part of > releasing, and we wouldn't end up with the issue where users cannot view > the latest released javadoc due to a site rebuild etc. > > Javadoc seems less important for some projects, Taglibs and Tomcat leap to > mind, so it may not apply for all (though seeing a tag doc in javadoc > style would rock). > > Anyway. Looking for community interest. If there, I'd make it my 2005 Q2 > task, probably along with trying to hassle on LGPL stuff again. > > As it's my current weapon of choice, I'd probably end up with an xml/xslt > solution much like the download stuff, so feel free to point out that that > wasy crap. > > Hen > > - > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Javadoc management
Interested in finding out if anyone else thinks this would be a good idea. Rather than have each subproject managing their release javadocs separately, I think it would be good if we treated the javadoc more like the releases. Located in a central location, perhaps mirrored, all versions available and perhaps with additional tools like ashkelon or multidoc to bring them together. Subprojects would still be hosting their latest cvs head javadocs internally, but they would deploy a versioned javadoc as a part of releasing, and we wouldn't end up with the issue where users cannot view the latest released javadoc due to a site rebuild etc. Javadoc seems less important for some projects, Taglibs and Tomcat leap to mind, so it may not apply for all (though seeing a tag doc in javadoc style would rock). Anyway. Looking for community interest. If there, I'd make it my 2005 Q2 task, probably along with trying to hassle on LGPL stuff again. As it's my current weapon of choice, I'd probably end up with an xml/xslt solution much like the download stuff, so feel free to point out that that wasy crap. Hen - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
