Support for maintaining old/multiple versions of site/documents by enabling ghpagesKeepVersions flag.

[kpritam]

Fixes #10

[lightbend-cla-validator]

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:

http://www.lightbend.com/contribute/cla

[kpritam]

Signed Lightbend CLA

[kpritam]

Is there any other better way to maintain versioning in ghpages published docs?

[julienrf]

@kpritam This contribution looks great! Do you mind adding a test for it? (in the sbt-test directory)

[kpritam]

@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.

[julienrf]

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?

[kpritam]

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

[julienrf]

we can copy

You mean sbt-doc or the users of sbt-doc? (Edit: sorry I meant sbt-ghpages)

[kpritam]

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
  }

[kpritam]

sbt-doc uses ghpages plugin, I have added workaround I mentioned above in sbt-doc plugin. As currently ghpages plugin does not support versioning.

[julienrf]

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?

[kpritam]

Sure, make sense!

[kpritam]

I have incorporated all these points in my last commit, let me know if those make sense!

[julienrf]

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?

[kpritam]

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.
Simplest way to achieve what you described could be setting ghpagesCopyLatestVersionAtRoot := false while releasing v1.1 (consumer of ghpages responsibility)
Or We could somehow keep track of published version and then sort and decide what goes at top level Or We could peek into current gh-pages repo to see what versions are published.

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…

ghpages plugin cleans repository at the time of every publish, hence this needs to be done in ghpages plugin.

[julienrf]

ghpages plugin cleans repository at the time of every publish, hence this needs to be done in ghpages plugin.

Alternatively, we could create a new folder for old versions each time we start a new major branch.

[kpritam]

ghpages plugin cleans repository at the time of every publish, hence this needs to be done in ghpages plugin.

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?