Spring-boot: Add a version navigation drop-down menu to the online documentation

[jmkgreen]

I am at

https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started-first-application.html

It would be really handy if there was a navigation drop-down menu listing the versions of Spring Boot for me to switch between. More important now that 2.0 is out, for people with older editions to maintain. Could not spot an open issue on this already.

[wilkinsona]

Thanks for the suggestion, but the documentation for each version of Spring Boot is tagged and released alongside the code. That means that it can't (easily) know about other versions, particularly those that have been released later. Our recommended entry point where you can see different versions with links to the documentation for each version is the project page.

[jmkgreen]

Could this not be simply in-lined as an HTML GET form submitting to a forwarding URL? You already know the historical versions. I know it's a manual maintenance task but it might be considered worth it. I do not know the documentation system you are using and am presuming an HTML form can be generated.

I suppose there are additional complexities such as locating the correct equivalent page and what to do if this doesn't exit. Elasticsearch have a good system I would love to see replicated.

[wilkinsona]

You already know the historical versions.

The historial versions are only part of it. I imagine that it's equally likely that someone looking at old documentation will want to switch to the up-to-date docs too.

Elasticsearch have a good system I would love to see replicated.

I've just looked at the Elasticsearch documentation and it does two things that I like:

1. Provides navigation from any version of the docs to any other version of the docs
2. Adds a banner to older documentation that links to the current documentation

I do not know the documentation system you are using and am presuming an HTML form can be generated.

Our documentation system's rather special… We write the docs in Asciidoctor (good) and then generate Docbook from the Asciidoctor source and then HTML, PDF, and ePUB, from the Docbook (bad).

What you're suggesting is possible with Asciidoctor as we could use a post-processor to inject some JavaScript into the generated HTML that adds the links and banner etc. It would require something serverside that provides details of all of the documentation versions. This would need to be robust for people viewing the docs offline too.

All of this would be a fairly significant amount of work and I'm not sure the benefits over the project page are worth it. Let's re-open this for now and see what the rest of the team and our docs expert, @buzzardo, think.

[wilkinsona]

Could this not be simply in-lined as an HTML GET form submitting to a forwarding URL?

I forgot the golden rule of open source. If you describe something as simple, you are honour-bound to provide a pull request that implements the suggestion.

[bclozel]

In my opinion, any documentation going for more integration between projects and multiple versions is a nice idea on paper.
Since we're using asciidoctor already, Antora could be a solution here. But I don't know if and how we should do that as it would require a complete rewrite on our side and re-generating all documentation.

[spring-projects-issues]

If you would like us to look at this issue, please provide the requested information. If the information is not provided within the next 7 days this issue will be closed.

[jmkgreen]

Perhaps someone would be kind enough to apply a "worth thinking about" or equivalent rather than simply allowing an automated closure of this?

[philwebb]

@jmkgreen I don't think there's much more that we can discuss on this issue and I'd rather have it closed than leave something open that we realistically won't get to.

I agree that it would be nice to find an easy way to navigate from one set of docs to another, but I don't think we should bake that into the Spring Boot docs themselves. I'm very much a fan on the current "self contained" nature of the docs and I don't like the idea of embedding anything too fancy into our HTML.

At one point the docs.spring.io site used to overlay a search bar when you viewed documentation. This had its own problems, but it would feel like a better place to solve the problem. Perhaps in the long term we can do something in https://github.com/spring-io/sagan.

[bclozel]

Sagan is not hosting the projects documentation/javadoc - static servers are - so it can't really add a search bar there.
On the other hand, we can improve the project pages in Sagan to better display the links to different versions.

[philwebb]

@bclozel I was thinking it could proxy access to docs.spring.io and modify the HTML 😱

[izeye]

Adding a link to the project page in the reference doc might be of some help here as there are some links to reference docs of recommend versions.