Support for maintaining old/multiple versions of site/documents by enabling ghpagesKeepVersions flag. #39
Conversation
|
Hi @kpritam, Thank you for your contribution! We really value the time you've taken to put this together. Before we proceed with reviewing this pull request, please sign the Lightbend Contributors License Agreement: |
|
Signed Lightbend CLA |
|
Is there any other better way to maintain versioning in ghpages published docs? |
|
@kpritam This contribution looks great! Do you mind adding a test for it? (in the sbt-test directory) |
I have added test, do have a look and let me know if thats fine. |
README.md
Outdated
| Behind the scenes, this flag plays two important roles: | ||
| 1. Set's the `includeFilter in ghpagesCleanSite` to include all the files from current versions. | ||
| (That means, if you publish same version again, old content from that version will be replaced by new content) | ||
| 2. While publishing site to gh-pages, new directory with current version's name is created and all the site contents will be |
There was a problem hiding this comment.
I think the fact that all the mappings will all be prefixed with the version number should be more emphasized.
Also, how would you recommend to do to have a page that automatically points to the latest version?
There was a problem hiding this comment.
For automatic pointing, we can copy latest version at top level as well as inside respective version directory. This can be filtered for snapshot versions which can reside only inside respective snapshot dirs.
We are doing exactly same here:
https://github.com/tmtsoftware/sbt-docs/blob/master/src/main/scala/org/tmt/sbt/docs/Settings.scala
There was a problem hiding this comment.
we can copy
You mean sbt-doc or the users of sbt-doc? (Edit: sorry I meant sbt-ghpages)
There was a problem hiding this comment.
In the GhpagesPlugin, when creating ghpagesPrivateMapping check can be added to detect if its a SNAPSHOT version or not and based on that generate mappings. Something like below:
private def ghpagesPrivateMappingsTask = Def.task {
val isSnapshot = version.value.contains("SNAPSHOT")
val makeSiteMappings = (mappings in SitePlugin.autoImport.makeSite).value
val updatedMappings =
if (ghpagesKeepVersions.value) {
val updated = makeSiteMappings map { case (file, target) => (file,
version.value + "/" + target) }
if(isSnapshot) upadated
else makeSiteMappings ++ updated
}
else makeSiteMappings
updatedMappings
}There was a problem hiding this comment.
sbt-doc uses ghpages plugin, I have added workaround I mentioned above in sbt-doc plugin. As currently ghpages plugin does not support versioning.
There was a problem hiding this comment.
OK. Do we want to add a setting key letting users control whether they want to have their website at the root in addition to have it prefixed by the version number?
There was a problem hiding this comment.
I have incorporated all these points in my last commit, let me know if those make sense!
…agesCopyLatestVersionAtRoot key, update README and test accordingly
|
Another question is coming to my mind. I am still not sure whether maintaining multiple versions should be done at the sbt-site level or sbt-ghpages level… With your proposal, would it be possible and easy to publish a website for v1.0 of a lib, then publish for v2.0, and then for v1.1 but while still having the website for 2.0 by default? |
As per the current proposal, last published version is copied to root directory as it does not know about previously published versions.
|
Alternatively, we could create a new folder for old versions each time we start a new major branch. |
This will force keeping older versions. What if people do not want older versions like the way ghpages currently behaves? |
Fixes #10