From 045973d7f638cb13fcf5b652946efbe145807194 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Thu, 10 Sep 2015 22:23:14 -0500 Subject: [PATCH 01/23] Add extra Markdown files as an option --- lib/ex_doc.ex | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/ex_doc.ex b/lib/ex_doc.ex index d5e1a8f93..a017bb1a7 100644 --- a/lib/ex_doc.ex +++ b/lib/ex_doc.ex @@ -14,7 +14,8 @@ defmodule ExDoc do source_url: nil, source_url_pattern: nil, version: nil, - logo: nil + logo: nil, + extras: [] ] end From 08bf56734379b1415619d94f2961e51879c9ef8d Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Thu, 10 Sep 2015 22:24:21 -0500 Subject: [PATCH 02/23] Add extra option to the usage documentation --- lib/ex_doc/cli.ex | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex index 1bbe221f7..1318f7b64 100644 --- a/lib/ex_doc/cli.ex +++ b/lib/ex_doc/cli.ex @@ -72,8 +72,9 @@ defmodule ExDoc.CLI do --source-ref Branch/commit/tag used for source link inference, default: "master" -m, --main The main, entry-point module in docs, default: "overview" when --formatter is "html" - -p --homepage-url URL to link to for the site name - -l --logo Path to the image logo of the project (only PNG or JPEG accepted) + -p, --homepage-url URL to link to for the site name + --extras Allow users to include additional Markdown files, default: [] + -l, --logo Path to the image logo of the project (only PNG or JPEG accepted) The image size will be 64x64 when --formatter is "html" default: `nil` From de04619782ae752a872b5e54f9966c3bfbaccdc7 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Thu, 10 Sep 2015 22:25:35 -0500 Subject: [PATCH 03/23] Use extra_template instead of readme_template --- lib/ex_doc/formatter/html.ex | 32 ++++++++++--------- lib/ex_doc/formatter/html/templates.ex | 2 +- ...readme_template.eex => extra_template.eex} | 0 3 files changed, 18 insertions(+), 16 deletions(-) rename lib/ex_doc/formatter/html/templates/{readme_template.eex => extra_template.eex} (100%) diff --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex index c534500d0..7c1676a23 100644 --- a/lib/ex_doc/formatter/html.ex +++ b/lib/ex_doc/formatter/html.ex @@ -28,7 +28,11 @@ defmodule ExDoc.Formatter.HTML do end if config.readme do - generate_readme(output, module_nodes, config, modules, exceptions, protocols) + generate_extra(config.readme, output, module_nodes, config, modules, exceptions, protocols) + end + + unless Enum.empty?(config.extras) do + generate_extras(output, module_nodes, config, modules, exceptions, protocols) end generate_index(output, config) @@ -89,9 +93,18 @@ defmodule ExDoc.Formatter.HTML do end end - defp generate_readme(output, module_nodes, config, modules, exceptions, protocols) do - readme_path = Path.expand(config.readme) - write_readme(output, File.read(readme_path), module_nodes, config, modules, exceptions, protocols) + defp generate_extras(output, module_nodes, config, modules, exceptions, protocols) do + config.extras + |> Enum.map(&Task.async(fn -> generate_extra(&1, output, module_nodes, config, modules, exceptions, protocols) end)) + |> Enum.map(&Task.await/1) + end + + defp generate_extra(input, output, module_nodes, config, modules, exceptions, protocols) do + file_path = Path.expand(input) + content = File.read!(file_path) |> Autolink.project_doc(module_nodes) + extra_html = Templates.extra_template(config, modules, exceptions, protocols, content) |> pretty_codeblocks + file_name = Path.basename(file_path, ".md") + File.write!("#{output}/#{file_name}.html", extra_html) end defp process_logo_metadata(config) do @@ -109,17 +122,6 @@ defmodule ExDoc.Formatter.HTML do end end - defp write_readme(output, {:ok, content}, module_nodes, config, modules, exceptions, protocols) do - content = Autolink.project_doc(content, module_nodes) - readme_html = Templates.readme_template(config, modules, exceptions, protocols, content) |> pretty_codeblocks - :ok = File.write("#{output}/README.html", readme_html) - true - end - - defp write_readme(_, _, _, _, _, _, _) do - false - end - defp generate_redirect(output, file_name, config, redirect_to) do content = Templates.redirect_template(config, redirect_to) :ok = File.write("#{output}/#{file_name}", content) diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex index fd8190ac3..c3f05f877 100644 --- a/lib/ex_doc/formatter/html/templates.ex +++ b/lib/ex_doc/formatter/html/templates.ex @@ -118,7 +118,7 @@ defmodule ExDoc.Formatter.HTML.Templates do not_found_template: [:config, :modules, :exceptions, :protocols], overview_entry_template: [:node], overview_template: [:config, :modules, :exceptions, :protocols], - readme_template: [:config, :modules, :exceptions, :protocols, :content], + extra_template: [:config, :modules, :exceptions, :protocols, :content], sidebar_template: [:config, :modules, :exceptions, :protocols], summary_template: [:node], type_detail_template: [:node, :_module], diff --git a/lib/ex_doc/formatter/html/templates/readme_template.eex b/lib/ex_doc/formatter/html/templates/extra_template.eex similarity index 100% rename from lib/ex_doc/formatter/html/templates/readme_template.eex rename to lib/ex_doc/formatter/html/templates/extra_template.eex From a09f5b3e4b599a9f6f5752f9e26c359d200bc1ec Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Thu, 10 Sep 2015 22:30:05 -0500 Subject: [PATCH 04/23] Add -l as an alias for --logo --- lib/ex_doc/cli.ex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex index 1318f7b64..8ac8b4c6f 100644 --- a/lib/ex_doc/cli.ex +++ b/lib/ex_doc/cli.ex @@ -2,7 +2,7 @@ defmodule ExDoc.CLI do def run(args, generator \\ &ExDoc.generate_docs/3) do {opts, args, _} = OptionParser.parse(args, aliases: [o: :output, f: :formatter, c: :config, r: :source_root, - u: :source_url, m: :main, p: :homepage_url]) + u: :source_url, m: :main, p: :homepage_url, l: :logo]) [project, version, source_beam] = parse_args(args) From 21abdfeee260cb03282908c169e9799c1575c3e9 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Thu, 10 Sep 2015 22:50:02 -0500 Subject: [PATCH 05/23] Add --extra option via command line --- lib/ex_doc/cli.ex | 13 +++++++++++-- mix.lock | 4 ++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex index 8ac8b4c6f..a88e0114b 100644 --- a/lib/ex_doc/cli.ex +++ b/lib/ex_doc/cli.ex @@ -2,7 +2,8 @@ defmodule ExDoc.CLI do def run(args, generator \\ &ExDoc.generate_docs/3) do {opts, args, _} = OptionParser.parse(args, aliases: [o: :output, f: :formatter, c: :config, r: :source_root, - u: :source_url, m: :main, p: :homepage_url, l: :logo]) + u: :source_url, m: :main, p: :homepage_url, l: :logo], + switches: [extra: :keep]) [project, version, source_beam] = parse_args(args) @@ -23,6 +24,14 @@ defmodule ExDoc.CLI do |> Keyword.put(:formatter_opts, read_config(config)) _ -> opts end + + extras = Keyword.get_values(opts, :extra) + unless Enum.empty?(extras) do + opts + |> Keyword.delete(:extra) + |> Keyword.put(:extras, extras) + end + opts end defp read_config(path) do @@ -73,7 +82,7 @@ defmodule ExDoc.CLI do -m, --main The main, entry-point module in docs, default: "overview" when --formatter is "html" -p, --homepage-url URL to link to for the site name - --extras Allow users to include additional Markdown files, default: [] + --extra Allow users to include additional Markdown files, default: [] -l, --logo Path to the image logo of the project (only PNG or JPEG accepted) The image size will be 64x64 when --formatter is "html" default: `nil` diff --git a/mix.lock b/mix.lock index 32df02b82..ec5051299 100644 --- a/mix.lock +++ b/mix.lock @@ -1,3 +1,3 @@ %{"earmark": {:hex, :earmark, "0.1.17"}, - "hoedown": {:git, "git://github.com/hoedown/hoedown.git", "2a4cf17c70e6572ed42cdca3ea7ca3e768ed17be", []}, - "markdown": {:git, "git://github.com/devinus/markdown.git", "cd0df79b6f1cc374499d47f6ba6aaab5096f874f", []}} + "hoedown": {:git, "https://github.com/hoedown/hoedown.git", "2a4cf17c70e6572ed42cdca3ea7ca3e768ed17be", []}, + "markdown": {:git, "https://github.com/devinus/markdown.git", "cd0df79b6f1cc374499d47f6ba6aaab5096f874f", []}} From 1a2a760848affcc6258d4ebaccf1a5840b735e5d Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 13:47:08 -0500 Subject: [PATCH 06/23] Improve config merge --- lib/ex_doc/cli.ex | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex index a88e0114b..7403c2aaa 100644 --- a/lib/ex_doc/cli.ex +++ b/lib/ex_doc/cli.ex @@ -17,6 +17,12 @@ defmodule ExDoc.CLI do end defp merge_config(opts) do + opts + |> formatter_options + |> extra_files_options + end + + defp formatter_options(opts) do case Keyword.fetch(opts, :config) do {:ok, config} -> opts @@ -24,14 +30,17 @@ defmodule ExDoc.CLI do |> Keyword.put(:formatter_opts, read_config(config)) _ -> opts end + end + defp extra_files_options(opts) do extras = Keyword.get_values(opts, :extra) - unless Enum.empty?(extras) do + if Enum.empty?(extras) do + opts + else opts |> Keyword.delete(:extra) |> Keyword.put(:extras, extras) end - opts end defp read_config(path) do From f338737bf5d9cfe19586bb518917e13d9e3981fb Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:14:14 -0500 Subject: [PATCH 07/23] Add extras and title option --- lib/ex_doc.ex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/ex_doc.ex b/lib/ex_doc.ex index a017bb1a7..8d674b2da 100644 --- a/lib/ex_doc.ex +++ b/lib/ex_doc.ex @@ -7,7 +7,6 @@ defmodule ExDoc do main: nil, output: "doc", project: nil, - readme: nil, retriever: ExDoc.Retriever, source_beam: nil, source_root: nil, @@ -15,7 +14,8 @@ defmodule ExDoc do source_url_pattern: nil, version: nil, logo: nil, - extras: [] + extras: [], + title: nil ] end From 2517561a096261f59efeb35cd370584b23faadeb Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:15:47 -0500 Subject: [PATCH 08/23] Sort items from Config struct --- lib/ex_doc.ex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/ex_doc.ex b/lib/ex_doc.ex index 8d674b2da..37b326830 100644 --- a/lib/ex_doc.ex +++ b/lib/ex_doc.ex @@ -1,9 +1,11 @@ defmodule ExDoc do defmodule Config do defstruct [ + extras: [], formatter: "html", formatter_opts: [], homepage_url: nil, + logo: nil, main: nil, output: "doc", project: nil, @@ -12,10 +14,8 @@ defmodule ExDoc do source_root: nil, source_url: nil, source_url_pattern: nil, - version: nil, - logo: nil, - extras: [], - title: nil + title: nil, + version: nil ] end From 3ec7964a9548d165924e318f7882afe9344aa1fe Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:17:24 -0500 Subject: [PATCH 09/23] Replace --readme option --- lib/ex_doc/cli.ex | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex index 7403c2aaa..5d54e6ad9 100644 --- a/lib/ex_doc/cli.ex +++ b/lib/ex_doc/cli.ex @@ -19,6 +19,7 @@ defmodule ExDoc.CLI do defp merge_config(opts) do opts |> formatter_options + |> replace_readme_option |> extra_files_options end @@ -32,6 +33,19 @@ defmodule ExDoc.CLI do end end + # TODO: At some point we need to mark the --readme option + # as deprecated. In the meantime, we put the README file + # into the extras list. + defp replace_readme_option(opts) do + case Keyword.fetch(opts, :readme) do + {:ok, readme} -> + opts + |> Keyword.delete(:readme) + |> Enum.into([extra: readme]) + _ -> opts + end + end + defp extra_files_options(opts) do extras = Keyword.get_values(opts, :extra) if Enum.empty?(extras) do From d0056cfa6a673b2fee89026bbf0eb3d1665ddc77 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:19:48 -0500 Subject: [PATCH 10/23] Generate README as an EXTRA --- lib/ex_doc/formatter/html.ex | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex index 7c1676a23..da6744605 100644 --- a/lib/ex_doc/formatter/html.ex +++ b/lib/ex_doc/formatter/html.ex @@ -27,10 +27,6 @@ defmodule ExDoc.Formatter.HTML do config = process_logo_metadata(config) end - if config.readme do - generate_extra(config.readme, output, module_nodes, config, modules, exceptions, protocols) - end - unless Enum.empty?(config.extras) do generate_extras(output, module_nodes, config, modules, exceptions, protocols) end @@ -101,10 +97,24 @@ defmodule ExDoc.Formatter.HTML do defp generate_extra(input, output, module_nodes, config, modules, exceptions, protocols) do file_path = Path.expand(input) - content = File.read!(file_path) |> Autolink.project_doc(module_nodes) - extra_html = Templates.extra_template(config, modules, exceptions, protocols, content) |> pretty_codeblocks - file_name = Path.basename(file_path, ".md") - File.write!("#{output}/#{file_name}.html", extra_html) + file_extname = + Path.extname(file_path) + |> String.downcase + + if file_extname == ".md" do + file_name = + Path.basename(file_path, ".md") + |> String.upcase + content = + File.read!(file_path) + |> Autolink.project_doc(module_nodes) + + config = Map.put(config, :title, file_name) + extra_html = Templates.extra_template(config, modules, exceptions, protocols, content) |> pretty_codeblocks + File.write!("#{output}/#{file_name}.html", extra_html) + else + raise ArgumentError, "File format not recognized, allowed format is: .md" + end end defp process_logo_metadata(config) do From 20bc1642ceed3c2de076f77f373460cf254edd26 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:21:34 -0500 Subject: [PATCH 11/23] Improve creation for EXTRA files --- lib/ex_doc/formatter/html/templates/extra_template.eex | 2 +- lib/ex_doc/formatter/html/templates/head_template.eex | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/ex_doc/formatter/html/templates/extra_template.eex b/lib/ex_doc/formatter/html/templates/extra_template.eex index 759469e08..b0cc30971 100644 --- a/lib/ex_doc/formatter/html/templates/extra_template.eex +++ b/lib/ex_doc/formatter/html/templates/extra_template.eex @@ -1,4 +1,4 @@ -<%= head_template(config, %{id: :readme}) %> +<%= head_template(config, %{id: :extra}) %> <%= sidebar_template(config, modules, exceptions, protocols) %> <%= to_html(content) %> diff --git a/lib/ex_doc/formatter/html/templates/head_template.eex b/lib/ex_doc/formatter/html/templates/head_template.eex index 24bbec1ea..029d3fe2c 100644 --- a/lib/ex_doc/formatter/html/templates/head_template.eex +++ b/lib/ex_doc/formatter/html/templates/head_template.eex @@ -7,8 +7,8 @@ <%= cond do %> <%= page.id == :module -> %> <title><%= page.module %> – <%= config.project %> v<%= config.version %> - <%= page.id == :readme -> %> - README – <%= config.project %> v<%= config.version %> + <%= page.id == :extra -> %> + <%= config.title %> – <%= config.project %> v<%= config.version %> <%= page.id == :overview -> %> Overview – <%= config.project %> v<%= config.version %> <% end %> From 33e2c3b3d7a9fd93d6d58a08167bdbf86918d16b Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:38:59 -0500 Subject: [PATCH 12/23] Keep backward compatibility --- lib/ex_doc.ex | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/ex_doc.ex b/lib/ex_doc.ex index 37b326830..247c10a8a 100644 --- a/lib/ex_doc.ex +++ b/lib/ex_doc.ex @@ -9,6 +9,7 @@ defmodule ExDoc do main: nil, output: "doc", project: nil, + readme: nil, retriever: ExDoc.Retriever, source_beam: nil, source_root: nil, From 6912b5bc674f78bfc6c3a74f413ce93e693c9685 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:39:38 -0500 Subject: [PATCH 13/23] Helper for extra files titles in the sidebar --- lib/ex_doc/formatter/html/templates.ex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex index c3f05f877..ef7d41494 100644 --- a/lib/ex_doc/formatter/html/templates.ex +++ b/lib/ex_doc/formatter/html/templates.ex @@ -110,6 +110,8 @@ defmodule ExDoc.Formatter.HTML.Templates do defp logo_path(%{logo: nil}), do: nil defp logo_path(%{logo: logo}), do: "assets/logo#{Path.extname(logo)}" + defp extra_title(path), do: path |> String.upcase |> Path.basename(".MD") + templates = [ detail_template: [:node, :_module], footer_template: [], From aa49c2765e11a55507c84f7c6e8e1237e22a8888 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:40:26 -0500 Subject: [PATCH 14/23] List all extra files in the sidebar area --- lib/ex_doc/formatter/html/templates/sidebar_template.eex | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/ex_doc/formatter/html/templates/sidebar_template.eex b/lib/ex_doc/formatter/html/templates/sidebar_template.eex index 50339c66c..94a3c911e 100644 --- a/lib/ex_doc/formatter/html/templates/sidebar_template.eex +++ b/lib/ex_doc/formatter/html/templates/sidebar_template.eex @@ -41,8 +41,10 @@
    - <%= if config.readme do %> -
  • README
    • + <%= unless Enum.empty?(config.extras) do %> + <%= for extra <- Enum.sort(config.extras) do %> +
  • <%= extra_title(extra) %>
    • + <%= end %> <% end %>
  • Overview
    • From 73233c0e86e890986918d37869e6bd2be3dc9e4c Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:43:59 -0500 Subject: [PATCH 15/23] Update template tests --- test/ex_doc/formatter/html/templates_test.exs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs index 161e2ef7f..988dae58b 100644 --- a/test/ex_doc/formatter/html/templates_test.exs +++ b/test/ex_doc/formatter/html/templates_test.exs @@ -19,7 +19,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do source_root: File.cwd!, source_url_pattern: "#{source_url}/blob/master/%{path}#L%{line}", homepage_url: homepage_url, - source_url: source_url, + source_url: source_url } end @@ -89,7 +89,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do end test "listing page has README link if present" do - config = Map.put(doc_config, :readme, "README.md") + config = Map.put(doc_config, :extras, ["README.md"]) content = Templates.sidebar_template(config, [], [], []) assert content =~ ~r{README} end From 6dbcfa96fa093c5c6143d0719a7408bcddc0ddc7 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:52:10 -0500 Subject: [PATCH 16/23] Update HTML formatter tests --- test/ex_doc/formatter/html_test.exs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/ex_doc/formatter/html_test.exs b/test/ex_doc/formatter/html_test.exs index 1adab0acb..0e4161f0a 100644 --- a/test/ex_doc/formatter/html_test.exs +++ b/test/ex_doc/formatter/html_test.exs @@ -33,7 +33,7 @@ defmodule ExDoc.Formatter.HTMLTest do output: "test/tmp/doc", source_root: beam_dir, source_beam: beam_dir, - readme: "test/tmp/README.md", + extras: ["test/tmp/README.md"] ] end @@ -151,7 +151,7 @@ defmodule ExDoc.Formatter.HTMLTest do end test "run should not generate the readme file" do - generate_docs(doc_config([readme: nil])) + generate_docs(doc_config([extras: []])) refute File.regular?("#{output_dir}/README.html") content = File.read!("#{output_dir}/index.html") refute content =~ ~r{README [^<]*} From 730b36edf3bac128bfc45f2a2cd69633554501da Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:52:49 -0500 Subject: [PATCH 17/23] Update minimum command-line options tests --- test/ex_doc_test.exs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/ex_doc_test.exs b/test/ex_doc_test.exs index 9c213e877..b969bc965 100644 --- a/test/ex_doc_test.exs +++ b/test/ex_doc_test.exs @@ -54,7 +54,7 @@ defmodule ExDocTest do assert project == "ExDoc" assert version == "1.2.3" - assert Enum.sort(opts) == [formatter_opts: [key: "val"], readme: "README.md", source_beam: "..."] + assert Enum.sort(opts) == [extras: ["README.md"], formatter_opts: [key: "val"], source_beam: "..."] after File.rm!("test.config") end From 06b1218e3ef29604aa714403f79cdeb9d31f84d0 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 15:55:29 -0500 Subject: [PATCH 18/23] Add an alias for --extra option --- lib/ex_doc/cli.ex | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex index 5d54e6ad9..e49260a34 100644 --- a/lib/ex_doc/cli.ex +++ b/lib/ex_doc/cli.ex @@ -2,7 +2,8 @@ defmodule ExDoc.CLI do def run(args, generator \\ &ExDoc.generate_docs/3) do {opts, args, _} = OptionParser.parse(args, aliases: [o: :output, f: :formatter, c: :config, r: :source_root, - u: :source_url, m: :main, p: :homepage_url, l: :logo], + u: :source_url, m: :main, p: :homepage_url, l: :logo, + e: :extra], switches: [extra: :keep]) [project, version, source_beam] = parse_args(args) @@ -105,7 +106,7 @@ defmodule ExDoc.CLI do -m, --main The main, entry-point module in docs, default: "overview" when --formatter is "html" -p, --homepage-url URL to link to for the site name - --extra Allow users to include additional Markdown files, default: [] + -e, --extra Allow users to include additional Markdown files, default: [] -l, --logo Path to the image logo of the project (only PNG or JPEG accepted) The image size will be 64x64 when --formatter is "html" default: `nil` From 69c096655c1723a0d9c2340fc1016c50013291e4 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 17:43:51 -0500 Subject: [PATCH 19/23] Replace :readme option in Mix task --- lib/mix/tasks/docs.ex | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index 9f18862a9..81f494a11 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -47,6 +47,9 @@ defmodule Mix.Tasks.Docs do * `:logo` - Path to the image logo of the project (only PNG or JPEG accepted) The image size will be 64x64 when --formatter is "html". + + * `:extras` - List of strings, each one must indicate the path to additional + Markdown pages (e.g. `["CHANGELOG.md", "CONTRIBUTING.md"]`); default: `[]` """ @doc false @@ -81,7 +84,9 @@ defmodule Mix.Tasks.Docs do options end - options = Keyword.put_new(options, :source_beam, Mix.Project.compile_path) + options = + Keyword.put_new(options, :source_beam, Mix.Project.compile_path) + |> replace_readme_option() index = generator.(project, version, options) log(index) @@ -101,4 +106,17 @@ defmodule Mix.Tasks.Docs do true -> docs end end + + # At some point we need to mark :readme option as + # deprecated. In the meantime, we put the README file + # into the :extras option. + defp replace_readme_option(opts) do + case Keyword.fetch(opts, :readme) do + {:ok, readme} -> + opts + |> Keyword.delete(:readme) + |> Keyword.update(:extras, readme, &(&1 ++ [readme])) + _ -> opts + end + end end From 3bc29f9aa782d45309cf31a7259f6464741b9759 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 18:18:35 -0500 Subject: [PATCH 20/23] Error message begins in lowercase --- lib/ex_doc/formatter/html.ex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex index da6744605..4681c411c 100644 --- a/lib/ex_doc/formatter/html.ex +++ b/lib/ex_doc/formatter/html.ex @@ -113,7 +113,7 @@ defmodule ExDoc.Formatter.HTML do extra_html = Templates.extra_template(config, modules, exceptions, protocols, content) |> pretty_codeblocks File.write!("#{output}/#{file_name}.html", extra_html) else - raise ArgumentError, "File format not recognized, allowed format is: .md" + raise ArgumentError, "file format not recognized, allowed format is: .md" end end From 6f69b61c3364cfe1795276e3d36dd399604441f5 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sat, 12 Sep 2015 18:48:10 -0500 Subject: [PATCH 21/23] Revert mix.lock --- mix.lock | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mix.lock b/mix.lock index ec5051299..32df02b82 100644 --- a/mix.lock +++ b/mix.lock @@ -1,3 +1,3 @@ %{"earmark": {:hex, :earmark, "0.1.17"}, - "hoedown": {:git, "https://github.com/hoedown/hoedown.git", "2a4cf17c70e6572ed42cdca3ea7ca3e768ed17be", []}, - "markdown": {:git, "https://github.com/devinus/markdown.git", "cd0df79b6f1cc374499d47f6ba6aaab5096f874f", []}} + "hoedown": {:git, "git://github.com/hoedown/hoedown.git", "2a4cf17c70e6572ed42cdca3ea7ca3e768ed17be", []}, + "markdown": {:git, "git://github.com/devinus/markdown.git", "cd0df79b6f1cc374499d47f6ba6aaab5096f874f", []}} From 7ee519800bb2d42830d7cb8529a2025899da74b9 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sun, 13 Sep 2015 03:37:09 -0500 Subject: [PATCH 22/23] Add sample for logo and extra options. --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 27baba34b..58463a987 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,9 @@ def project do name: "REPO", source_url: "https://github.com/USER/REPO", homepage_url: "http://YOUR_PROJECT_HOMEPAGE", - logo: "path/to/logo.png", - deps: deps] + deps: deps, + docs: [logo: "path/to/logo.png", + extras: ["README.md", "CONTRIBUTING.md"]]] end ``` From d4ff7b230e55a58e0dea8c861a1e36ff3751ce48 Mon Sep 17 00:00:00 2001 From: Milton Mazzarri Date: Sun, 13 Sep 2015 03:41:27 -0500 Subject: [PATCH 23/23] Remove readme option from CLI and Mix --- lib/ex_doc.ex | 1 - lib/ex_doc/cli.ex | 15 --------------- lib/mix/tasks/docs.ex | 22 ++-------------------- test/ex_doc_test.exs | 2 +- 4 files changed, 3 insertions(+), 37 deletions(-) diff --git a/lib/ex_doc.ex b/lib/ex_doc.ex index 247c10a8a..37b326830 100644 --- a/lib/ex_doc.ex +++ b/lib/ex_doc.ex @@ -9,7 +9,6 @@ defmodule ExDoc do main: nil, output: "doc", project: nil, - readme: nil, retriever: ExDoc.Retriever, source_beam: nil, source_root: nil, diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex index e49260a34..72e974715 100644 --- a/lib/ex_doc/cli.ex +++ b/lib/ex_doc/cli.ex @@ -20,7 +20,6 @@ defmodule ExDoc.CLI do defp merge_config(opts) do opts |> formatter_options - |> replace_readme_option |> extra_files_options end @@ -34,19 +33,6 @@ defmodule ExDoc.CLI do end end - # TODO: At some point we need to mark the --readme option - # as deprecated. In the meantime, we put the README file - # into the extras list. - defp replace_readme_option(opts) do - case Keyword.fetch(opts, :readme) do - {:ok, readme} -> - opts - |> Keyword.delete(:readme) - |> Enum.into([extra: readme]) - _ -> opts - end - end - defp extra_files_options(opts) do extras = Keyword.get_values(opts, :extra) if Enum.empty?(extras) do @@ -97,7 +83,6 @@ defmodule ExDoc.CLI do VERSION Version number BEAMS Path to compiled beam files -o, --output Path to output docs, default: "doc" - --readme Path to README.md file to generate a project README, default: `nil` -f, --formatter Docs formatter to use, default: "html" -c, --config Path to the formatter's config file -r, --source-root Path to the source code root, default: "." diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index 81f494a11..57d9b5414 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -26,9 +26,6 @@ defmodule Mix.Tasks.Docs do * `:output` - output directory for the generated docs; default: "doc". May be overriden by command line argument. - * `:readme` - string denoting the source file for a project README - (e.g., "README.md"); default: `nil` (no README created). - * `:formatter` - doc formatter to use; default: "html". * `:source_root` - path to the source code root directory; @@ -49,7 +46,7 @@ defmodule Mix.Tasks.Docs do The image size will be 64x64 when --formatter is "html". * `:extras` - List of strings, each one must indicate the path to additional - Markdown pages (e.g. `["CHANGELOG.md", "CONTRIBUTING.md"]`); default: `[]` + Markdown pages (e.g. `["README.md", "CONTRIBUTING.md"]`); default: `[]` """ @doc false @@ -84,9 +81,7 @@ defmodule Mix.Tasks.Docs do options end - options = - Keyword.put_new(options, :source_beam, Mix.Project.compile_path) - |> replace_readme_option() + options = Keyword.put_new(options, :source_beam, Mix.Project.compile_path) index = generator.(project, version, options) log(index) @@ -106,17 +101,4 @@ defmodule Mix.Tasks.Docs do true -> docs end end - - # At some point we need to mark :readme option as - # deprecated. In the meantime, we put the README file - # into the :extras option. - defp replace_readme_option(opts) do - case Keyword.fetch(opts, :readme) do - {:ok, readme} -> - opts - |> Keyword.delete(:readme) - |> Keyword.update(:extras, readme, &(&1 ++ [readme])) - _ -> opts - end - end end diff --git a/test/ex_doc_test.exs b/test/ex_doc_test.exs index b969bc965..168af6605 100644 --- a/test/ex_doc_test.exs +++ b/test/ex_doc_test.exs @@ -50,7 +50,7 @@ defmodule ExDocTest do test "command-line config" do File.write!("test.config", ~s([key: "val"])) - {project, version, opts} = run(["ExDoc", "--readme", "README.md", "1.2.3", "...", "-c", "test.config"]) + {project, version, opts} = run(["ExDoc", "--extra", "README.md", "1.2.3", "...", "-c", "test.config"]) assert project == "ExDoc" assert version == "1.2.3"