From bb9498d6b743b401cf8a1da28e3e72d9d79f71d6 Mon Sep 17 00:00:00 2001 From: Jason Axelson Date: Sun, 6 Apr 2025 07:49:46 -1000 Subject: [PATCH 1/3] Document the requirement to push releases Currently there isn't any documentation about the requirement to push releases/tags to the `source_url` to get links to specific versions of the code. So this PR adds this documentation. I couldn't find a general spot where `source_url` is talked about so I added an admonition near where it is first introduced. --- lib/mix/tasks/docs.ex | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index c9bc1f808..d4e5260be 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -58,6 +58,14 @@ defmodule Mix.Tasks.Docs do ] end + > #### Tip {: .info} + > + > If you set `:source_url` to a GitHub/GitLab/BitBucket repo then whenever you + > publish a release you should publish the release to the repo (which will + > push a tag). If the release exists in the repo then ex_doc will generate + > links to the specific version of the code that the user is currently + > browsing. + ExDoc also allows configuration specific to the documentation to be set. The following options should be put under the `:docs` key in your project's main configuration. The `:docs` options should From f07fa163cc26b444d40d919ddf86a6aec68d414e Mon Sep 17 00:00:00 2001 From: Jason Axelson Date: Tue, 8 Apr 2025 06:10:03 -1000 Subject: [PATCH 2/3] Update lib/mix/tasks/docs.ex MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: José Valim --- lib/mix/tasks/docs.ex | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index d4e5260be..cdb146cd3 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -61,10 +61,9 @@ defmodule Mix.Tasks.Docs do > #### Tip {: .info} > > If you set `:source_url` to a GitHub/GitLab/BitBucket repo then whenever you - > publish a release you should publish the release to the repo (which will - > push a tag). If the release exists in the repo then ex_doc will generate - > links to the specific version of the code that the user is currently - > browsing. + > publish a new version of your package, you should run `git tag vVERSION` + > and push the tag. This way, ExDoc will generate links to the specific version + > the docs were generated for. ExDoc also allows configuration specific to the documentation to be set. The following options should be put under the `:docs` key From e3ff122ca5d489164b1fcb67b736a1540c54b765 Mon Sep 17 00:00:00 2001 From: Jason Axelson Date: Sat, 12 Apr 2025 09:24:07 -1000 Subject: [PATCH 3/3] Give the source_ref/source_url its own section --- lib/mix/tasks/docs.ex | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index cdb146cd3..a2f2f99ee 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -58,13 +58,6 @@ defmodule Mix.Tasks.Docs do ] end - > #### Tip {: .info} - > - > If you set `:source_url` to a GitHub/GitLab/BitBucket repo then whenever you - > publish a new version of your package, you should run `git tag vVERSION` - > and push the tag. This way, ExDoc will generate links to the specific version - > the docs were generated for. - ExDoc also allows configuration specific to the documentation to be set. The following options should be put under the `:docs` key in your project's main configuration. The `:docs` options should @@ -205,13 +198,13 @@ defmodule Mix.Tasks.Docs do * `%{path}`: the path of a file in the repo * `%{line}`: the line number in the file - For GitLab/GitHub: + For self-hosted GitLab/GitHub: ```text https://mydomain.org/user_or_team/repo_name/blob/main/%{path}#L%{line} ``` - For Bitbucket: + For self-hosted Bitbucket: ```text https://mydomain.org/user_or_team/repo_name/src/main/%{path}#cl-%{line} @@ -221,6 +214,37 @@ defmodule Mix.Tasks.Docs do where path is either an relative path from the cwd, or an absolute path. The function must return the full URI as it should be placed in the documentation. + ### Using `:source_url` and `:source_ref` together + + A common setup for a project or library is to set both `:source_url` and `:source_ref`. Setting + both of them will allow ExDoc to link to specific version of the code for a function or module + that matches the version of the docs. So if the docs have been generated for version 1.0.5 then + clicking on the source link in the docs will take the browser to the source code for the 1.0.5 + version of the code instead of only the primary ref (e.g. `main`). + + A example setup looks like: + + @version "0.30.10" + def project do + [ + ... + version: @version, + docs: docs(), + ... + ] + end + + def docs do + ... + source_ref: "v#{@version}", + source_url: @source_url, + ... + end + + If you use `source_ref: "v#{@version}"` then when publishing a new version of your package you + should run `git tag vVERSION` and push the tag. This way, ExDoc will generate links to the + specific version the docs were generated for. + ## Groups ExDoc content can be organized in groups. This is done via the `:groups_for_extras`