[hibernate-dev] Minor issues/questions about Hibernate Core/ORM documentation

[Gail Badner]

I've kept http://docs.jboss.org/hibernate/core/ as is with 4.0.1.Final documentation and:
- added a symbolic link for http://docs.jboss.org/hibernate/orm/ that points to http://docs.jboss.org/hibernate/core/ 
- updated the symbolic link for http://docs.jboss.org/hibernate/stable/core/ to point to http://docs.jboss.org/hibernate/core/4.0/
- added a symbolic link http://docs.jboss.org/hibernate/stable/orm/ that points to http://docs.jboss.org/hibernate/stable/core/

Steve, are you thinking that the hem doc will be merged into main docs for 4.0.2 or for 4.1?

Regards,
Gail 
----- Original Message -----
> From: "Steve Ebersole" <steve at hibernate.org>
> To: "Hardy Ferentschik" <hardy at hibernate.org>
> Cc: "Hibernate" <hibernate-dev at lists.jboss.org>
> Sent: Thursday, January 12, 2012 1:48:46 PM
> Subject: Re: [hibernate-dev] Minor issues/questions about Hibernate Core/ORM documentation
> 
> 
> On Thu 12 Jan 2012 03:19:29 AM CST, Hardy Ferentschik wrote:
> > Answers inline
> >
> > On Jan 12, 2012, at 9:50 AM, Gail Badner wrote:
> >
> >> I've uploaded the 4.0.1.Final documentatation to
> >> http://docs.jboss.org/hibernate/core/4.0/.
> >>
> >> Maybe this was already discussed but, should the switch from
> >> "core" to "orm" affect the URL for the 4.0 documentation (i.e.,
> >> http://docs.jboss.org/hibernate/orm/4.0/)?
> >
> > I think it makes sense to switch the urls. However, in this case I
> > suggest we also put a redirect in place for
> > http://docs.jboss.org/hibernate/core/4.0/ to
> > http://docs.jboss.org/hibernate/orm/4.0/
> > Just renaming the directories is probably not a good idea due to
> > bookmarks and people used to go to the 'core' url. If we change to
> > orm we need to update the pointers from
> > http://www.hibernate.org/docs
> 
> I agree, we should do a redirect.  I had not planned on changing the
> physical dir until 4.1 as that is when the new docs would be getting
> used.  6 in one... if you feel the itch, go for it.
> 
> 
> >> Also, I noticed that http://docs.jboss.org/hibernate/stable/core/
> >> points to 3.6.9.Final docs. Should it point to
> >> http://docs.jboss.org/hibernate/core/4.0/ (or
> >> http://docs.jboss.org/hibernate/orm/4.0/)?
> >
> > Stable should definitely point to 4.0. That's independent of
> > whether we rename the urls
> + 1
> 
> 
> >> I ended up using the documentation downloaded from the SourceForge
> >> distribution because I got errors when I tried to build the
> >> Javadoc from the 4.0.1 tag using "gradle javadoc":
> >>
> >> /NotBackedUp/gbadner/git/hibernate-core-master/hibernate-core/src/main/java/org/hibernate/metamodel/source/annotations/HibernateDotNames.java:109:
> >> cannot find symbol
> >> symbol  : variable DotName
> >> location: interface
> >> org.hibernate.metamodel.source.annotations.HibernateDotNames
> >>         DotName ACCESS_TYPE = DotName.createSimple(
> >>         AccessType.class.getName() );
> >>
> >> What command should be used to build Javadoc?
> >
> > 'gradle javadoc' is the default javadoc task which you get when you
> > use the Java plugin. It build the javadocs for the current module.
> > In our case we don't use this task, because
> > we want aggregated docs. To get the aggregated docs you need to run
> > the 'aggregateJavadocs' from the release module.
> >
> > './gradlew aggregateJavadocs'
> 
> Just a minor point.  If you run it from the release module, it has to
> be
> `../gradlew aggregateJavadocs`
> 
> Alternatively from root you could run `./gradlew
> :release:aggregateJavadocs`
> 
> 
> > FYI, the javadoc task needs all dependencies on the classpath when
> > executing. Looking at the error it seems jandex is not on the
> > classpath. This might be related to HHH-6921, but that's just a
> > guess.
> > As said, the default javadocs tasks are not configured, because we
> > are only interested in the aggregated docs.
> 
> I think Strong only changed that to move jandex to the provided
> configuration.  I was able to run these fine when I did the build.
> 
> 
> >> I also noticed that the Javadoc includes test classes. It would be
> >> nice to exclude those.
> >
> > right, even the aggregated docs seem to include test classes. I
> > would create a jira and we reconfigure the task for the next
> > release
> 
> Hmm, I spent a lot of time getting those right.
> https://fisheye2.atlassian.com/changelog/Hibernate-Core?cs=39d47c4b39f231435305b47e23f4b2cf8e9aede8#releaseZ002frelease.gradle
> 
> If they are back, something after fucked those changes up.
> 
> 
> >> I really liked how convenient it was to be able to just copy the
> >> contents of the documentation directory from the distribution
> >> into the staging directory for rsync-ing. The only change I had
> >> to make after copying was to change hem/en to hem/en-US. I
> >> haven't looked into this, but I imagine that would be an easy
> >> thing to fix.
> 
> We should update that in the source tree.  But to be honest, hem docs
> should really just go away as a separate thing.  Their content should
> be
> merged into the main docs.
> 
> 
> >
> >
> > _______________________________________________
> > hibernate-dev mailing list
> > hibernate-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/hibernate-dev
> --
> steve at hibernate.org
> http://hibernate.org
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>