Running ExDoc on CI for both Elixir 1.6 and 1.7

Questions / Help
1

ex_doc is playing some jokes on me…

I have a library that I’d like to test on CI with Elixir 1.7 and OTP21. BUT I’d also like to test against OTP20 and Elixir 1.6. The thing is: I usually build the docs on CI just to confirm I haven’t broken anything there.

Currently, I either disable doc building on CI or I don’t test with latest versions. Is there something I can do on this scenario? And if there is not, shouldn’t the version bump be major?

Anyway, the docs are way nicer on 0.19. Thanks for all the work invested there.

1 Like
2

It’s a bit tricky, but it’s possible to do this. However, before I get to that I wanted to note that according to SemVer spec 2.0 0.x.y versions do not come with any compatibility guarantees.

ExDoc version requirement based on Elixir version

One option would be to determine the ExDoc version requirement based on the current Elixir version:

  defp deps do
    [
      {:ex_doc, ex_doc_version(), only: :dev, runtime: false}
    ]
  end

  defp ex_doc_version do
    if System.version() >= "1.7", do: "~> 0.19", else: "~> 0.18.0"
  end

The drawback of this approach is that you now have an inconsistent mix.lock file between different Elixir versions. This might not be a problem if you primarily work with 1.7 and just want to include 1.6 on CI.

Use ExDoc 0.18 from escript

Another approach would be to stick to "~> 0.19" in your deps and use the older version from an escript install. On your CI if it’s running with 1.6 you would need something like this to generate the docs:

$ mix escript.install hex ex_doc '~> 0.18.0'
$ mix compile # there will be some warnings relating to ex_doc 0.19, but those can be ignored
$ path/to/escripts/ex_doc YourProject 0.1.0 _build/dev/lib/your_project/ebin -m YourProject

I prefer this approach because it avoids the mix.lock inconsistency and restricts the necessary changes to your CI configuration.

2 Likes
3

Thanks for your ideas! I haven’t considered the escript path!

I was wrong about semver… If any moderator could change the title to “ex_doc 0.19 breaks CI on Elixir 1.6” I’d appreciate. Thanks for noting that.

In any case, I wonder if such an if couldn’t be inside ex_doc 0.19 itself. Anyway, thanks once again for your help. Cheers.

4

I have the same problem. :frowning:

5

I think the ex_doc_version trick is a good solution. Alternatively you can set {:ex_doc, ..., only: :docs} and run with MIX_ENV=docs mix docs only on latest Elixir version (eg depending on env var on CI)

6

Thank you! We run generating docs in Travis. So our CI will fail for either 1.6 or 1.7 :joy: