make docs on Mac - scala docs failure

[aaronmarkham]

Description

Making docs on a Mac is broken if you use the latest version of scala, maven, and sbt.

Minimum reproducible example

On a Mac, run make docs.
Unrelated, but this actually fails unless you do make first.

Then you'll see you need some dependencies like in the setup_docs_ubuntu script and then follow up with these to make sure you're getting the system installs for Mac (you must have Sphinx 1.5.6 just like CI):

pip install sphinx==1.5.6
brew install maven
brew upgrade maven
brew install sbt
brew install scala
make
make docs

That's pretty much what I had to do to get the docs to get even close to building on the Mac.
But, then it will fail when it tries to move some scala docs files that don't exist.

What have you tried to solve it?

I sort of solved it, but it isn't something I think I can commit because it might break what's happening in CI on Ubuntu.

1. Remove index and package.html from mxdoc.py line 89
2. Run make docs again and it's fine. Even better than fine, because the docs seem to be much more modern and usable than the current docs.

Comments

If you get stuck building docs locally with a Mac, do what I did in step 1 above.
I'd like to see how to upgrade the Ubuntu scaladocs in CI to what I'm seeing on the Mac. CI docker setup uses no version info when installing the scala deps, so it's not obvious at the moment. Acquiring a different version of scala deps would need to be thoroughly tested since it could break any number of other things.

[aaronmarkham]

I compared versions.

mac

maven 3.5.3
java 1.8.0_171
scala 2.12.6

ubuntu

maven 3.3.9
java 1.8.0_162
scala 2.11.6
sbt 1.1.5

I believe the fix for this - to get Mac and Ubuntu on the same version scala, and this will fix the Mac docs build, by getting everything to work with the latest version of scala:

1. Remove index and package.html from mxdoc.py line 89
2. For CI and general Ubuntu deps, run the following:

sudo apt-get remove scala-library scala
sudo wget http://scala-lang.org/files/archive/scala-2.12.6.deb
sudo dpkg -i scala-2.12.6.deb

You go from 2000 and late.
To 2000 and next.

[lanking520]

Is adding platform check in mxdoc.py could be a solution to this for short term? I think we really need a version control for dependencies of docs, update them on a timely manner.

[aaronmarkham]

This will pin Scala. Sbt and Maven should be pinned too. Would need to dig further on how that would work for those. Also, even for this Scala upgrade, we'd want to see if it has any impact.

[safrooze]

@sandeep-krishnamurthy I don't think this is a Doc issue. This is a bug in building docs, so I'd recommend removing Doc and Scala label and adding Bug and Build labels.