Fix site generation for new repository structure
Description
Environment
Activity
With the fixes from last week, the snapshot site is much improved. It’s far from perfect, but I’m going to declare it as good enough and meeting the intent of this issue.
The most obvious departure from what you’d expect is that the parent link on the main module claims to point to the Shibboleth parent project but is actually a relative link leading nowhere. I found a ticket complaining about this kind of behaviour many years ago with more than 700 “me too”s and I have not been able to find a simple solution. It’s actually less broken than the snapshot site for the IdP, but that in turn is probably because of the parent-as-sibling structure there.
If we needed to fix this properly, I can’t see an alternative that involves a single inherited site.xml file. Instead, you need a site.xml in every module as well (although they could be symbolic links to a resource in the mda-parent). Given that I'm minded to drop the site entirely, that seems like more work than we need to put in.
Closing as “good enough”.
Commit 034c40088d98e52b0e3056a36f8baa17917598f6 fixes most of the issues as well as adding some minor new content. Most of the problems came down to Maven’s inheritance model and some left-over configuration.
I was not able to upgrade maven-site-plugin at this time because of new dependencies.
I was unable to remove the link to the project’s parent from just the root module, which is what I had wanted. I need to check that it’s rendering correctly on the actual publication site after the nightlies have run. The links back up from the modules do seem to be correct, though.
The (snapshot) site gets published to here: http://shibboleth.net/sites/snapshot/java-metadata-aggregator/0.10.0-SNAPSHOT/index.html
The link from there to the Shibboleth parent project is broken.
The “for more information” link in the description to the wiki page isn’t rendered, but perhaps it should be removed (there must be another place it could go).
The two key lists modules have the same text as the (MDA) parent, and need custom text.
Really much closer to functional than I remember. Huzzah!
Just to be on the safe side, updating the maven-site-plugin to the latest 3.x version.
Important note from the site plugin’s documentation:
Note: If you have a multi module project, then the links between the parent and child modules will not work when you use
mvn siteormvn site:site. If you want to use those links, you should usemvn site:stageinstead. You can read more about that goal further down on this page in the section called 'Staging a Site'.
I don’t think that was my problem, but these specific links do seem to be working for me just now, at least locally. So it may be that things have improved, or I may have been mistaken.
Since the repository was reorganised in MDA-263, the generated site has been a bit wonky, to say the least.
For example, It looks like the generated root has broken links to the module sites, because they aren't correctly relativised. This leaves the links inoperative.
I'd also note that there's a link in the POM's `<description>` that points to the Confluence space but isn't rendered in the site. It might be nice to fix that in passing, although I note that some of our other projects have the same thing, and although not best practice and hard to use it's hard to see it as a priority on its own.