Docs do not accurately describe how to install plugin

[benhutchison]

Top hit in google: http://www.scala-sbt.org/sbt-native-packager/

Getting started says:

Add it to your plugins.sbt
addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "x.y.z")

Version shown in the docs 1.1

Fail :( [warn] :: com.typesafe.sbt#sbt-native-packager;1.1: not found

Root cause is the artifacts are being published under a different version string (1.1.0-RC1) to what the docs advertise.

[muuki88]

Thanks for your report. This isn't ideal. I'm not that familiar with sphinx, but there should definitely be an option to use the full version.

On the github page we do have the bintray version badge and the docs states x.y.z. But this is not ideal.

[weedySeaDragon]

The docs can reflect the current version by putting a variable into the documentation file gettingstarted.rst and using the PreProcess plugin (which is already available in sbt-site). You can set the value of the variable to the current version, and then run a preprocess task before the sphinx documentation is generated.

IOW, put this variable into gettingstarted.rst where you want the version to show up: @VERSION@. In build.sbt set the value that will be used for @VERSION@ when PreProcess replaces it and also ensure that preprocess will deal with *.rst files:

  preprocessVars in Preprocess := Map(  "VERSION" -> version.value)
  preprocessIncludeFilter in Preprocess ++= "*.rst"
  // probably also need to also define source... and target in Preprocess

I can do a PR, but I'm not sure what task handles generating the sphinx documentation. That task needs to include the preprocessing. If someone can tell me where that happens and what makes sense for including preprocessing, I can do this pretty easily.

[muuki88]

We migrated to readthedocs.org to support multiple documentation versions. What we haven't done yet is redirecting the scala-sbt.org address. This is due to the fact that the API documentation is still hosted on github. This leads to the following state:

scala-sbt.org/sbt-native-packager	sbt-native-packager.readthedocs.io
- Scaladoc	- all releases
- Last release	- latest and stable version

Readthedocs builds the documentation from src/sphinx. Version numbers are fine here as readthedocs uses the tag to display the version.

I guess setting the correct PreProcess variables should fix this issue. Could you try making a PR and I take a look if it works smoothly together with readthedocs?

[weedySeaDragon]

Thanks for the really clear explanation. Since I've always been starting at github, I've always been viewing scala-sbt.org/sbt-native-packager/ -- and so didn't realize that that sbt-native-packager.readthedocs.io site existed and was different.

Right now, I just want to get the code example in Getting Started to display helpful info and the current version. Something like:

Sbt-native-packager is an AutoPlugin. Add it to your plugins.sbt

addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "x.y.z")  // replace "x.y.z" with the version you want to use

The current version is 1.2.0

The version for the package (in build.sbt) is 1.2.0-SNAPSHOT. I don't know how to get rid of the -SNAPSHOT qualifier. Is there some setting or value that already has that info? I could certainly write a bit of code to get it, but I figured someone else has already done it. It smelled like sbt-release would make that accessible, but it wasn't obvious to me.

In doing some digging and testing, I learned that sphinx already has variables for version and release. (version is the one typically used without the qualifier.) So we don't even have to use PreProcess -- we just have to set the values for sphinxInputs

EDIT: On second thought, if your build process for Read The Docs is standard, then Read The Docs is going to get values (like the version and copyright info) from the .../src/sphinx/config.py file. So we may need to use PreProcess to get the right values into that file.

Let me know if there's an easy way to get the version without the qualifier (or not) and I'll do the PR.

[muuki88]

and so didn't realize that that sbt-native-packager.readthedocs.io site existed and was different

That's still a problem, yes. Not sure what's a good solution to this ( hadn't had the time to think about it).

Let me know if there's an easy way to get the version without the qualifier

You smelled right. sbt-release changes the version number during the release and removes the -SNAPSHOT qualifier. So if you build from a release tag commit (e.g. 1.2.0-M5 you should get a proper version.

if your build process for Read The Docs is standard, then Read The Docs is going to get values (like the version and copyright info) from the .../src/sphinx/config.py file

Currently read-the-docs does the right thing. So I'm not sure if we need to change anything there?

[ennru]

This is still a problem. An easy fix would be to add a link to the releases page on Github so the user can easily find out about available versions.

[muuki88]

That's a good suggestion @ennru

My idea was to add a simple sbt task that replaces the version in the README.md on a release, so I can't forget ;)

[muuki88]

Fixed in #1084

[ahoy-jon]

Are you sure it's fixed? I see that? On this page: https://www.scala-sbt.org/sbt-native-packager/gettingstarted.html

---

There is nothing helping on the internet for this kind of issue:

[error] (update) sbt.librarymanagement.ResolveException: Error downloading com.typesafe.sbt:sbt-native-packager;sbtVersion=1.0;scalaVersion=2.12:1.9.9

The correct line in the plugin.sbt is:

addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.9.9")

[muuki88]

read the docs is a mess I haven't been able to fix until now. There are doc pages for older versions that still contain the old description.