From 0174d030c28d4240da6cc540bcb78b10ff0ac153 Mon Sep 17 00:00:00 2001 From: Kevin Litchfield Date: Fri, 16 Jun 2017 15:55:27 -0400 Subject: [PATCH] Link `

` headings --- lib/ex_doc/formatter/html/templates.ex | 24 +++++++++---------- test/ex_doc/formatter/html/templates_test.exs | 15 +++++++++++- test/ex_doc/formatter/html_test.exs | 6 ++--- test/ex_doc/retriever_test.exs | 6 ++--- test/fixtures/compiled_with_docs.ex | 11 +++++++++ 5 files changed, 43 insertions(+), 19 deletions(-) diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex index 25ee86046..2fc7f4b45 100644 --- a/lib/ex_doc/formatter/html/templates.ex +++ b/lib/ex_doc/formatter/html/templates.ex @@ -232,35 +232,35 @@ defmodule ExDoc.Formatter.HTML.Templates do end @doc """ - Link secondary headings found with `regex` with in the given `content`. - IDs are prefixed with `prefix`. + Link headings found with `regex` with in the given `content`. IDs are + prefixed with `prefix`. """ - @h2_regex ~r/(.*?)<\/h2>/m + @heading_regex ~r/<(h[23]).*?>(.*?)<\/\1>/m @spec link_headings(String.t, Regex.t, String.t) :: String.t - def link_headings(content, regex \\ @h2_regex, prefix \\ "") + def link_headings(content, regex \\ @heading_regex, prefix \\ "") def link_headings(nil, _, _), do: nil def link_headings(content, regex, prefix) do - Regex.replace(regex, content, fn match, title -> - link_heading(match, title, header_to_id(title), prefix) + Regex.replace(regex, content, fn match, tag, title -> + link_heading(match, tag, title, header_to_id(title), prefix) end) end - defp link_heading(match, _title, "", _prefix), do: match - defp link_heading(_match, title, id, prefix) do + defp link_heading(match, _tag, _title, "", _prefix), do: match + defp link_heading(_match, tag, title, id, prefix) do """ -

+ <#{tag} id="#{prefix}#{id}" class="section-heading"> #{title} -

+ """ end defp link_moduledoc_headings(content) do - link_headings(content, @h2_regex, "module-") + link_headings(content, @heading_regex, "module-") end defp link_detail_headings(content, prefix) do - link_headings(content, @h2_regex, prefix <> "-") + link_headings(content, @heading_regex, prefix <> "-") end templates = [ diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs index 8d8790ad5..313c10573 100644 --- a/test/ex_doc/formatter/html/templates_test.exs +++ b/test/ex_doc/formatter/html/templates_test.exs @@ -107,6 +107,13 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do

""") + + assert Templates.link_headings("

Foo

") == """ +

+ + Foo +

+ """ end test "sidebar items from headers" do @@ -163,6 +170,11 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do "Example function: Summary should not display trailing puntuation" end + test "

tags in method `@doc`s are linked" do + content = get_module_page([CompiledWithDocs]) + assert content =~ ~r{

.*.*.*.*Examples.*

}ms + end + ## LISTING test "site title text links to homepage_url when set" do @@ -210,6 +222,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do refute content =~ ~r{module} assert content =~ ~r{moduledoc.*Example.*CompiledWithDocs\.example.*}ms assert content =~ ~r{

.*.*.*.*Example.*

}ms + assert content =~ ~r{

.*.*.*.*Example H3 heading.*

}ms # Summaries assert content =~ ~r{example/2.*Some example}ms @@ -217,7 +230,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do assert content =~ ~r{example_1/0.*\(macro\)}ms # Source - assert content =~ ~r{]*>\s*\s*View Source\s*}ms + assert content =~ ~r{]*>\s*\s*View Source\s*}ms # Functions assert content =~ ~s{
} diff --git a/test/ex_doc/formatter/html_test.exs b/test/ex_doc/formatter/html_test.exs index 7b2d693f5..d257cb2f7 100644 --- a/test/ex_doc/formatter/html_test.exs +++ b/test/ex_doc/formatter/html_test.exs @@ -45,15 +45,15 @@ defmodule ExDoc.Formatter.HTMLTest do for scheme <- ["http", "https"] do generate_docs doc_config(source_url: "#{scheme}://github.com/elixir-lang/ex_doc", source_root: File.cwd!) content = File.read!(file_path) - assert content =~ "https://github.com/elixir-lang/ex_doc/blob/master/test/fixtures/compiled_with_docs.ex#L13" + assert content =~ "https://github.com/elixir-lang/ex_doc/blob/master/test/fixtures/compiled_with_docs.ex#L14" generate_docs doc_config(source_url: "#{scheme}://gitlab.com/elixir-lang/ex_doc", source_root: File.cwd!) content = File.read!(file_path) - assert content =~ "https://gitlab.com/elixir-lang/ex_doc/blob/master/test/fixtures/compiled_with_docs.ex#L13" + assert content =~ "https://gitlab.com/elixir-lang/ex_doc/blob/master/test/fixtures/compiled_with_docs.ex#L14" generate_docs doc_config(source_url: "#{scheme}://bitbucket.org/elixir-lang/ex_doc", source_root: File.cwd!) content = File.read!(file_path) - assert content =~ "https://bitbucket.org/elixir-lang/ex_doc/src/master/test/fixtures/compiled_with_docs.ex#cl-13" + assert content =~ "https://bitbucket.org/elixir-lang/ex_doc/src/master/test/fixtures/compiled_with_docs.ex#cl-14" generate_docs doc_config(source_url: "#{scheme}://example.com/elixir-lang/ex_doc", source_root: File.cwd!) content = File.read!(file_path) diff --git a/test/ex_doc/retriever_test.exs b/test/ex_doc/retriever_test.exs index 01381b89d..87d8df97b 100644 --- a/test/ex_doc/retriever_test.exs +++ b/test/ex_doc/retriever_test.exs @@ -46,7 +46,7 @@ defmodule ExDoc.RetrieverTest do test "docs_from_files returns the moduledoc info" do [module_node] = docs_from_files ["CompiledWithDocs"] - assert module_node.doc == "moduledoc\n\n\#\# Example ☃ Unicode > escaping\n CompiledWithDocs.example\n" + assert module_node.doc == "moduledoc\n\n\#\# Example ☃ Unicode > escaping\n CompiledWithDocs.example\n\n### Example H3 heading\n\nexample\n" end test "docs_from_files returns nil if there's no moduledoc info" do @@ -56,7 +56,7 @@ defmodule ExDoc.RetrieverTest do test "docs_from_files returns the doc info for each module function" do [module_node] = docs_from_files ["CompiledWithDocs"] - [struct, example, example_1, example_without_docs] = module_node.docs + [struct, example, example_1, _example_with_h3, example_without_docs] = module_node.docs assert struct.id == "__struct__/0" assert struct.doc == "Some struct" @@ -74,7 +74,7 @@ defmodule ExDoc.RetrieverTest do assert example_1.type == :defmacro assert example_1.defaults == [] - assert example_without_docs.source_url == "http://example.com/test/fixtures/compiled_with_docs.ex\#L18" + assert example_without_docs.source_url == "http://example.com/test/fixtures/compiled_with_docs.ex\#L29" assert example_without_docs.doc == nil assert example_without_docs.defaults == [] end diff --git a/test/fixtures/compiled_with_docs.ex b/test/fixtures/compiled_with_docs.ex index 0a41dde1d..add45f136 100644 --- a/test/fixtures/compiled_with_docs.ex +++ b/test/fixtures/compiled_with_docs.ex @@ -4,6 +4,10 @@ defmodule CompiledWithDocs do ## Example ☃ Unicode > escaping CompiledWithDocs.example + + ### Example H3 heading + + example """ @doc "Some struct" @@ -15,6 +19,13 @@ defmodule CompiledWithDocs do @doc "Another example" defmacro example_1, do: 1 + @doc """ + Does example action. + + ### Examples + """ + def example_with_h3, do: 1 + def example_without_docs, do: nil defmodule Nested do