Skip to content

Add skip_code_autolink_to option #1759

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.

Sign up for GitHub

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 2 commits into from
Sep 4, 2023
Merged

Add skip_code_autolink_to option #1759

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b0c4527
Add skip_code_autolink_to option
viniciusmuller Sep 2, 2023
9700f76
Add more docs
viniciusmuller Sep 2, 2023
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
5 changes: 4 additions & 1 deletion lib/ex_doc/autolink.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ defmodule ExDoc.Autolink do
# * `:extras` - map of extras
#
# * `:skip_undefined_reference_warnings_on` - list of modules to skip the warning on
#
# * `:skip_code_autolink_to` - list of terms that will be skipped when autolinking (e.g: "PrivateModule")

defstruct [
:current_module,
Expand All @@ -32,7 +34,8 @@ defmodule ExDoc.Autolink do
deps: [],
ext: ".html",
siblings: [],
skip_undefined_reference_warnings_on: []
skip_undefined_reference_warnings_on: [],
skip_code_autolink_to: []
]

@hexdocs "https://hexdocs.pm/"
Expand Down
2 changes: 2 additions & 0 deletions lib/ex_doc/config.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ defmodule ExDoc.Config do
project: nil,
retriever: ExDoc.Retriever,
skip_undefined_reference_warnings_on: [],
skip_code_autolink_to: [],
source_beam: nil,
source_ref: @default_source_ref,
source_url: nil,
Expand Down Expand Up @@ -75,6 +76,7 @@ defmodule ExDoc.Config do
project: nil | String.t(),
retriever: atom(),
skip_undefined_reference_warnings_on: [String.t()],
skip_code_autolink_to: [String.t()],
source_beam: nil | String.t(),
source_ref: nil | String.t(),
source_url: nil | String.t(),
Expand Down
6 changes: 4 additions & 2 deletions lib/ex_doc/formatter/html.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ defmodule ExDoc.Formatter.HTML do
deps: config.deps,
ext: ext,
extras: extra_paths(config),
skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on
skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
skip_code_autolink_to: config.skip_code_autolink_to
]

project_nodes
Expand Down Expand Up @@ -375,7 +376,8 @@ defmodule ExDoc.Formatter.HTML do
deps: config.deps,
ext: ext,
extras: extra_paths(config),
skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on
skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
skip_code_autolink_to: config.skip_code_autolink_to
]

extras =
Expand Down
8 changes: 8 additions & 0 deletions lib/ex_doc/language/elixir.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -559,6 +559,14 @@ defmodule ExDoc.Language.Elixir do
end

defp url(string, mode, config) do
if Enum.any?(config.skip_code_autolink_to, &(&1 == string)) do
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we allow regexes here as well?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can add if necessary later on? Unless you have an immediate need for it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I deprecated a module, so I'd like to do ~r/MyMod(\..*)?/ basically instead of having to list the references to the module alone and then to all the functions I mention. Unless I'm reading the feature wrong 😉

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if this would ever come up but the above regex will also catch MyNamespace.MyMod. So maybe it should be: ~r/^MyMod(\..*)?/. but then we'd still warn on callbacks and types so I suppose ~r/^([bt]:)?MyMod(\..*)?/.

I think we can add the regex support but it needs to be used carefully. but yeah I'd rather have users spell out things explicitly to keep the code explicit too. how annoying is this gonna be for you? is this for a changelog? If so consider just cutting off old changelog entries, e.g. write:

The CHANGELOG for v1.15 and previous releases can be found [in the v1.15] branch

or something like that.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we just make it a function and allow you to pass anything?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, +1 from me.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will merge this and we can make both skip_ options accept a function too.

nil
else
parse_url(string, mode, config)
end
end

defp parse_url(string, mode, config) do
case Regex.run(~r{^(.+)/(\d+)$}, string) do
[_, left, right] ->
with {:ok, arity} <- parse_arity(right) do
Expand Down
6 changes: 6 additions & 0 deletions lib/mix/tasks/docs.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,12 @@ defmodule Mix.Tasks.Docs do
skip the warnings, for a given module/function/callback/type (e.g.: `["Foo", "Bar.baz/0"]`)
or on a given file (e.g.: `["pages/deprecations.md"]`); default: `[]`.

* `:skip_code_autolink_to` - Similar to `:skip_undefined_reference_warnings_on`, this option
controls which terms will be skipped by ExDoc when building documentation.
Useful for example if you want to highlight private modules or functions
without warnings (e.g.: `["PrivateModule", "PrivateModule.func/1"]`);
default: `[]`.

* `:source_beam` - Path to the beam directory; default: mix's compile path.

* `:source_ref` - The branch/commit/tag used for source link inference;
Expand Down
14 changes: 14 additions & 0 deletions test/ex_doc/language/elixir_test.exs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -381,6 +381,20 @@ defmodule ExDoc.Language.ElixirTest do
~s[t() :: <a href="https://hexdocs.pm/elixir/String.html#t:t/0">String.t</a>()]
end

test "skips autolinking if requested" do
ExDoc.Refs.insert([
{{:module, AutolinkTest.Hidden}, :hidden},
{{:function, AutolinkTest.Hidden, :foo, 1}, :hidden}
])

assert_skip_autolink_no_warn("AutolinkTest.Hidden")
assert_skip_autolink_no_warn("AutolinkTest.Hidden.foo/1")
end

defp assert_skip_autolink_no_warn(string) do
assert_unchanged(~m(`#{string}`), skip_code_autolink_to: [string])
end

test "Elixir basic types" do
assert autolink_spec(quote(do: t() :: atom())) ==
~s[t() :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>()]
Expand Down