Maven 2.x and 3.x Site Plugin

When I change the hostname to it's IP address, it works.

This happens because the site plugin tries to make all URLs relative, when possible. I think that you have something like this defined in the pom.xml for this project:

<url>http://sirdsite.dsths.ad.dstcorp.net/x/y/z/</url>

where x, y and z are some directory names.

It would be helpful if you could provide the URL that this project says it will be deployed to. This URL is then used to determine if there are any relative paths that will get to links specified in the site.xml.

For the most recent one:
<site>
<id>sites</id>
<url>scp://sirdsite.dsths.ad.dstcorp.net/var/www/html/maven2-sites/common/ConstraintEngine-1.0.6-SNAPSHOT</url>
</site>

Actually, I sort of worked this one out for myself. The problem, I think, was that I was deploying to a host alias and referencing a FQDN in a link (or vice versa). Things got a little confusing when I tried to view the generated site documentation off the filesystem (oops). Since I now deploy all sites to a standardized location and all URLs are standardized to reference that location, it all works.
I think the issue I really had wasn't that it didn't work but rather that it violates the Principle of Least Astonishment.
This may be the right way to handle this, although based on my minor experience with multi-module builds it's probably designed to handle those cases specifically (I guess?).

I now understand the issue and have been able to provide appropriate changes to my poms to conform to "The Way" and the dependencies report produces the correct links to our internal sites.

Perhaps the thing that is needed the most is a bit of documentation that explains actually what transpires within the site generation process? I would be happy to write that documentation but I don't actually know for sure exactly what happens, although I do seem to know a bit more than I did a couple of months ago.

What else can I do to help?

Love the 'Principle of Least Astonishment' reference. Yes you're right that this feature was designed primarily to enable the relocation of maven sites without having to regenerate them with new POM defined URLs. Also worthy of note is that you can not reliable use ${expressions} in the POM project.URL as site has to look up and down the project hierarchy (parent and module links) and when building without a reactor (ie you're only building a child project on its own not the entire hierarchy) one can not always get the 'cooked' (interpolated) versions of these POM files and will thus have URLs containing the uninterpolated ${} values. Solution to that is to always use the complete project hierarchy in a reactor build to generate a site. Anyway I digress.

I guess this was always intended for links to maven generated pages so maybe we could, and we should defer to brett here, modify the site.xml link element to support a new attribute that indicates that a link should not be resolved to a relative URL? A more drastic solution would be to provide a site mojo configuration option to disbale relatives altogether but then you;d be kicking yourself when you needed to relocate someone else's mirrored site.

In terms of the docs, by all means please supply a patch to the site pages for the plugin, maybe something in the FAQ or in the examples. It's always good to make folk aware of the behaviour of the system

By the way, there is a site:stage mojo that will lay the site out (deploy) to a local folder on your machine so you can test the resulting generated site out without having to deploy it to its real location. This mojo also supports a deploy option (see docs) which will then deploy that 'staged' site to a remote location allowing you to share the 'staged' site with others via HTTP.

I have added an FAQ entry for this.

I ran into the "URLs containing uninterpolated ${}" digression in John's comment 2 hops above. In my case it was a failure to expand a property defined in settings.xml, and in this case it is not clear why this expansion is not done when the child site is generated by itself. Before reading this I had opened http://jira.codehaus.org/browse/MSITE-310.

Now I see it is a known issue, but it does seem like a reasonable idea to put the deployment location in settings.xml, and there should be no issue with the context this property needs to be resolved from.