Skip to content

Document the requirement to push releases #2109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 13, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions lib/mix/tasks/docs.ex
Original file line number Diff line number Diff line change
@@ -198,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}
@@ -214,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`