Add an option to specify a particular commit/branch/tag for source links

[alco]

No description provided.

[alco]

This PR will allow us to tweak Makefile for Elixir and close #32.

[alco]

Now I'm in doubt if master is a good default. It is probably more reasonable to use current rev. If the user wants master, they case set :source_ref to "master" which is easier to do than to set it to current rev.

[alco]

Another issue that users might have to deal with is when they need to generate documentation for a new version of their project and they want to use the most recent tag for source links, they'll need to modify the :source_ref option.

To solve this, in general case, project config should probably look like this:

def project do
  [ source_ref: get_ref ]
end

defp get_ref do
  # calculate the desired ref
end

We could make this easier on the user by providing helpers like ExDoc.source_ref(:most_recent_tag), ExDoc.source_ref(:HEAD), etc.

[josevalim]

The problem with ExDoc.source_ref(:HEAD) is that it would be executed for every mix command, effectively slowing things down. :) Maybe we should just allow setting it to an atom and, if that is the case, we expand the atom (like :HEAD would have special semantics).

[josevalim]

Can we add a small test?

[josevalim]

Thanks a lot! ❤️

[alco]

The problem with ExDoc.source_ref(:HEAD) is that it would be executed for every mix command, effectively slowing things down.

It's true. But if we don't provide those helpers, users will write their own function for retrieving a suitable ref and it'll run for every mix command. I think we need to come up with a way to be able to specify such a function but make it run only once.

[alco]

Even though mix.exs is compiled in-memory, can we reference it during the doc generation process? I'm think of this

def project do
  [ source_ref: {__MODULE__, :get_ref } ]
  # or even
  [ source_ref: function(__MODULE__.get_ref/0) ]
end

def get_ref do
  # calculate the desired ref
end

[josevalim]

A function would work perfectly too.