scala/scala-xml

Publish API docs somehow

ashawley opened this issue · 5 comments

ashawley commented

I believe the compiler's build would publish the scala-xml docs to scala-lang.org/api.

Now that the scala-xml dependency was ripped out of the compiler, it probably won't any longer.

I guess we could just migrate to github-pages or something.

ashawley commented

Last night, I published the API docs for scala-xml to the gh-pages branch, so they show up here:

https://scala.github.io/scala-xml/api/1.1.0/scala/xml/

I created a really primitive index.html file for navigating all the historical versions.

https://scala.github.io/scala-xml/api/

If motivated, we can snazz it up later.

Using GitHub pages went smoothly and it was convenient to publish this way, but I'm not sure if it's the best solution.

  1. I wrongly assumed the scala-lang.org site was hosted on GitHub pages, so I thought what I did would show up at www.scala-lang.org/scala-xml/. I guess www.scala-lang.org is still located on EPFL servers. It would be better if this were on the scala-lang.org domain, rather than exposing scala.github.io.
  2. After publishing the docs for 8 old versions of scala-xml to gh-pages, there is now a branch on this repo with 100 megabytes of uncompressed data. Everyone who forks and clones the repo typically retrieves the gh-pages branch. Git does a good job with compression, but it grows the compressed size of the repo from 2M to 5M.

The only thing I found that publishes to scala.github.io is the actor migration project.

For (2), maybe we should only publish the latest API docs to reduce the file size, and not the historical versions?

SethTisue commented

It would be better if this were on the scala-lang.org domain, rather than exposing scala.github.io

hmm, I don't know, maybe using scala.github.io is okay, actually. @fsalvi opinion?

Git does a good job with compression, but it grows the compressed size of the repo from 2M to 5M

doesn't bother me, 5M is still small, and my guess is that as more versions are added, the size won't grow very fast since the additions will be so similar to the other files.

if the repo eventually gets too big, fsvo "too big", I think we could deal it with it then. (unlike on the main branches, on the gh-pages branch we can git filter-branch to our heart's content)

ashawley commented

Yes, the compiler used to publish the docs for scala-xml to scala-lang.org, but that won't be the case going forward.

ashawley commented

Ok, we will go with publishing scala-xml docs on scala.github.io. It works for me.