6:33 a.m.
Hi all!
So here is a status of what I did:
- I updated the /stable/ link of ogm from 3.0 (cough, cough) to 5.0:
http://docs.jboss.org/hibernate/stable/ogm/reference/en-US/html/: we
need to include this in our release process.
- I updated the /current/ symlink of ORM to point to 5.2 instead of
5.1: it needs to be integrated in the release process; (the /stable/
link uses the /current/ symlink so it's also fixed)
- I removed the docs for OGM 3.0 as they were a copy of the doc of OGM 4.2
Next, I applied some magic to 2 old versions of OGM and Search so that
you can check everything is OK for you before I generalize it:
- Add meta description and keywords
- Add a canonical link to the /stable/ single html version
- Add a piece of Javascript to warn the user and propose to redirect
him to the best possible place of our last stable release
documentation
See the 2 examples here:
http://docs.jboss.org.local/hibernate/ogm/4.1/reference/en-US/html/ogm-ar...
(scroll to see the hash tracker in action)
http://docs.jboss.org/hibernate/search/4.2/reference/en-US/html/search-ar...
See the current code and descriptors here:
https://docs.jboss.org/hibernate/_outdated-content/
The script and the descriptors work for all existing versions of the
OGM and Search doc.
The marker to include in the docs looks like that:
<script src="//code.jquery.com/jquery-3.1.0.min.js"
integrity="sha256-cCueBR6CsyA4/9szpPfrX3s49M9vUU5BgtiJj06wt/s="
crossorigin="anonymous"></script>
<script src="/hibernate/_outdated-content/outdated-content.js"
type="text/javascript"></script>
<script type="text/javascript">$(document).ready(function() {
HibernateDoc.OutdatedContent.install("search"); });</script>
(I'm using a CDN but maybe we should host jQuery on docs.jboss.org?)
The script is capable to redirect either to the multi page version
(using the redirects declared in the JSON file: it automatically
cumulates the redirects from version X to version Y so we don't need
that much metadata) or to the single page version by leveraging the
anchors and hashes. For now, I decided to push the user to the single
page version as it's the one we use for the canonical link but we can
of course discuss it. Note that I add a ?v=X.X parameter to be sure
the user is redirected to a fresh version of the corresponding
/stable/ page and not a cache. I had the issue a couple of times.
Next if you like it:
- generalize it to all the existing versions of the docs, sed FTW
- modify the Hibernate XSL stylesheets to include it in the newly generated ones
- probably modify our website so that the stable release points to the
/stable/ link to the docs
- do the same for Validator
@ORM: interested in me pursuing this for ORM too? It will probably be
a lot more work as the structure of the docs got changed a lot.
Comments, opinions, thoughts welcome.
--
Guillaume
On Wed, Jul 20, 2016 at 12:06 PM, Davide D'Alto <davide(a)hibernate.org> wrote:
I'll try to apply these changes on Friday.
Davide
On Tue, Jul 19, 2016 at 11:53 PM, Guillaume Smet
<guillaume.smet(a)gmail.com> wrote:
> Hi Sanne,
>
> Thanks for your feedback. I was pretty sure I hadn't all the history!
>
> Getting Google to prioritize our latest doc is probably a long time goal.
>
> I played a bit with jQuery to suggest to the user to go to the latest
> stable. Note that I only took into consideration the page for the time
> being and didn't consider the anchor but it should be easy to add it
> if we think it's worth it (it's a lot more work on the json descriptor
> though).
>
> The following command for each version is all that is needed:
> sed -i 's@</body>@<script
> src="http://code.jquery.com/jquery-3.1.0.min.js"
> integrity="sha256-cCueBR6CsyA4/9szpPfrX3s49M9vUU5BgtiJj06wt/s="
> crossorigin="anonymous"></script><script
>
src="/hibernate/search/outdated-version.js"></script></body>@'
*.html
> (or a find -exec to do it on all the versions at once)
>
> I attached the global json descriptor and the js file (with a .txt
> extension as it didn't pass the mail filter). Both should be added to
> /hibernate/search/. Note that I only did the work for version 4.5 in
> the json descriptor. The work for other versions would mostly be a
> copy/paste.
>
> I also attached a screenshot of how it looks like. Nothing fancy but
> we can do whatever we want.
>
> Note that I only targeted the multi page HTML output as it was the
> most interesting to prototype.
>
> When we release a new version, we would have to update the descriptor file.
>
> Comments?
>
> --
> Guillaume