Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document how to keep older api docs around #10

Open
eed3si9n opened this issue Jun 19, 2015 · 4 comments · May be fixed by #39
Open

Document how to keep older api docs around #10

eed3si9n opened this issue Jun 19, 2015 · 4 comments · May be fixed by #39

Comments

@eed3si9n
Copy link
Member

When I use sbt-site and sbt-ghpages plugin to publish Scala docs, I mostly never want it to wipe out the older pages. Could we either document how now to do that, or have some settings for a pattern of pages that it doesn't wipe out?
@rossabaker
Copy link

👍. I've been working around this same problem and came here to look for a better solution.

@rossabaker rossabaker mentioned this issue Jul 13, 2015
Closed
@ches
Copy link

ches commented Mar 11, 2016

👍 as well, and further, the current documentation lies:

> help ghpagesPushSite
Pushes a generated site into the ghpages branch.  Will not clean the branch unless you run clean-site first.

Note the second sentence, which appears to expressly suggest that existing content will be left alone, but reading the plugin code pushSite invokes syncLocal, which subsequently always invokes cleanSiteForRealz and 💥 there goes all the previously existing content.

As a guideline to help get people started, below is how I have set things up in hopes of generating (and retaining) versioned copies of Scaladoc. I'd be happy to work this into a contribution of plugin documentation, but as of now it falls short since ghpagesPushSite is always clobbering all the content of gh-pages—as @eed3si9n suggests the plugin seems to need some modification to support this conveniently.

// project/plugins.sbt
resolvers += "jgit-repo" at "http://download.eclipse.org/jgit/maven"

addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.0.0-RC3")
addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.5.4")
// build.sbt
autoAPIMappings := true
scalacOptions in (Compile, doc) ++= Seq(
  "-doc-title", "My Project",
  "-doc-version", version.value,
  "-groups"
)

enablePlugins(SiteScaladocPlugin)
siteSubdirName in SiteScaladoc := s"api/${version.value}"

// Builds static files in src/site-preprocess with variable substitution.
enablePlugins(PreprocessPlugin)
preprocessVars := Map("VERSION" -> version.value)

// Enables easy publishing to project's gh-pages.
ghpages.settings
git.remoteRepo := "git@github.com:ches/my-project.git"
<!-- src/site-preprocess/index.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Project Documentation</title>
    <script>
      <!--
      function doRedirect() {
        window.location.replace("api/@VERSION@/org/mygroup/myproject/package.html");
      }

      doRedirect();
      //-->
    </script>
  </head>

  <body>
    <a href="api/@VERSION@/org/mygroup/myproject/package.html">Go to the project documentation</a>
  </body>
</html>

@ches ches mentioned this issue Mar 11, 2016
Merged
@arashi01 arashi01 mentioned this issue Mar 30, 2016
Merged
@kpritam kpritam linked a pull request Feb 1, 2018 that will close this issue
Open
@Lasering
Copy link

I'm trying to accomplish the same task but with a different implementation.
Instead of creating the index.html pointing to the latest version. I'm trying to commit a symlink which points to latest version. But somehow the symlink is lost (aka converted to a regular folder).

@Lasering
Copy link

Doing it manually

  1. In build.sbt add:
enablePlugins(SiteScaladocPlugin)
siteSubdirName in SiteScaladoc := s"api/${version.value}"
  1. Execute sbt ghpagesSynchLocal
  2. Go the the ghpages repo dir (you can find it by typing ghpagesRepository in sbt console)
  3. Execute:
cd api
ln -s <your version> latest
  1. Commit and push on that repo.

This works it creates the correct content at Github Pages.

Trying to automate it

  1. In build.sbt add:
val latestDir = settingKey[String]("the latest api dir")
latestDir := "api/latest"
addMappingsToSiteDir(mappings in SiteScaladoc, latestDir)
  1. Go to the ghpagesRepository. Now there is a folder named latest inside the folder api with the same content as the folder <your version>. This means that if now commit and push it will have the desired effect. But we will be committing all the files in duplicate, which is wasteful to say the least.

So the missing step is how to create the correct symlink inside ghpagesRepository.

@imsdu imsdu mentioned this issue Jun 9, 2021
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
4 participants
@ches @rossabaker @eed3si9n @Lasering