From 6721301086674afe721f9eea478a2037756be93c Mon Sep 17 00:00:00 2001 From: Alex S Date: Fri, 30 Aug 2019 19:14:01 +0300 Subject: [PATCH] some changes --- config/description.exs | 15 ++++---- lib/mix/tasks/pleroma/docs.ex | 6 +-- .../docs/{formatter.ex => generator.ex} | 6 ++- lib/pleroma/docs/json.ex | 5 ++- lib/pleroma/docs/markdown.ex | 38 ++++++++++++------- 5 files changed, 44 insertions(+), 26 deletions(-) rename lib/pleroma/docs/{formatter.ex => generator.ex} (90%) diff --git a/config/description.exs b/config/description.exs index 537b9d996..684d3fc0e 100644 --- a/config/description.exs +++ b/config/description.exs @@ -1,5 +1,5 @@ use Mix.Config -alias Pleroma.Docs.Formatter +alias Pleroma.Docs.Generator websocket_config = [ path: "/websocket", @@ -24,7 +24,7 @@ type: :module, description: "Module which will be used for uploads", suggestions: [ - Formatter.uploaders_list() + Generator.uploaders_list() ] }, %{ @@ -32,7 +32,7 @@ type: {:list, :module}, description: "List of filter modules for uploads", suggestions: [ - Formatter.filters_list() + Generator.filters_list() ] }, %{ @@ -64,8 +64,7 @@ %{ key: :proxy_opts, type: :keyword, - description: "Proxy options, see `Pleroma.ReverseProxy` documentation", - suggestions: ["somehow created link to Pleroma.ReverseProxy options"] + description: "Proxy options, see `Pleroma.ReverseProxy` documentation" } ] }, @@ -93,7 +92,7 @@ children: [ %{ key: :bucket, - type: :strings, + type: :string, description: "S3 bucket", suggestions: [ "bucket" @@ -629,7 +628,7 @@ description: "A list of MRF policies enabled", suggestions: [ Pleroma.Web.ActivityPub.MRF.NoOpPolicy, - Formatter.mrf_list() + Generator.mrf_list() ] }, %{ @@ -1920,7 +1919,7 @@ type: {:list, :module}, description: "list of Rich Media parsers", suggestions: [ - Formatter.richmedia_parsers() + Generator.richmedia_parsers() ] }, %{ diff --git a/lib/mix/tasks/pleroma/docs.ex b/lib/mix/tasks/pleroma/docs.ex index d68e02383..821ee74f9 100644 --- a/lib/mix/tasks/pleroma/docs.ex +++ b/lib/mix/tasks/pleroma/docs.ex @@ -8,11 +8,11 @@ defmodule Mix.Tasks.Pleroma.Docs do Supports two formats: `markdown` and `json`. - ## Generate markdown docs + ## Generate Markdown docs `mix pleroma.docs` - ## Generate json docs + ## Generate JSON docs `mix pleroma.docs json`s """ @@ -30,7 +30,7 @@ defp do_run(implementation) do {descriptions, _paths} = Mix.Config.eval!("config/description.exs") {:ok, file_path} = - Pleroma.Docs.Formatter.process( + Pleroma.Docs.Generator.process( implementation, descriptions[:pleroma][:config_description] ) diff --git a/lib/pleroma/docs/formatter.ex b/lib/pleroma/docs/generator.ex similarity index 90% rename from lib/pleroma/docs/formatter.ex rename to lib/pleroma/docs/generator.ex index a1c757936..e788712cc 100644 --- a/lib/pleroma/docs/formatter.ex +++ b/lib/pleroma/docs/generator.ex @@ -1,4 +1,4 @@ -defmodule Pleroma.Docs.Formatter do +defmodule Pleroma.Docs.Generator do @callback process(keyword()) :: {:ok, String.t()} @spec process(module(), keyword()) :: {:ok, String.t()} @@ -6,6 +6,7 @@ def process(implementation, descriptions) do implementation.process(descriptions) end + @spec uploaders_list() :: [module()] def uploaders_list do {:ok, modules} = :application.get_key(:pleroma, :modules) @@ -17,6 +18,7 @@ def uploaders_list do end) end + @spec filters_list() :: [module()] def filters_list do {:ok, modules} = :application.get_key(:pleroma, :modules) @@ -27,6 +29,7 @@ def filters_list do end) end + @spec mrf_list() :: [module()] def mrf_list do {:ok, modules} = :application.get_key(:pleroma, :modules) @@ -38,6 +41,7 @@ def mrf_list do end) end + @spec richmedia_parsers() :: [module()] def richmedia_parsers do {:ok, modules} = :application.get_key(:pleroma, :modules) diff --git a/lib/pleroma/docs/json.ex b/lib/pleroma/docs/json.ex index 38f015017..aed730e78 100644 --- a/lib/pleroma/docs/json.ex +++ b/lib/pleroma/docs/json.ex @@ -1,5 +1,7 @@ defmodule Pleroma.Docs.JSON do - @behaviour Pleroma.Docs.Formatter + @behaviour Pleroma.Docs.Generator + + @spec process(keyword()) :: {:ok, String.t()} def process(descriptions) do config_path = "docs/generate_config.json" {:ok, file} = File.open(config_path, [:write]) @@ -9,6 +11,7 @@ def process(descriptions) do {:ok, config_path} end + @spec generate_json([keyword()]) :: String.t() def generate_json(descriptions) do Jason.encode!(descriptions) end diff --git a/lib/pleroma/docs/markdown.ex b/lib/pleroma/docs/markdown.ex index 27a096631..c66640bf1 100644 --- a/lib/pleroma/docs/markdown.ex +++ b/lib/pleroma/docs/markdown.ex @@ -1,16 +1,17 @@ defmodule Pleroma.Docs.Markdown do - @behaviour Pleroma.Docs.Formatter + @behaviour Pleroma.Docs.Generator + @spec process(keyword()) :: {:ok, String.t()} def process(descriptions) do config_path = "docs/config.md" {:ok, file} = File.open(config_path, [:write]) - IO.write(file, "# Generated configuration\r\n\r\n") + IO.write(file, "# Configuration\r\n\r\n") IO.write(file, "Date of generation: #{Date.utc_today()}\r\n\r\n") IO.write( file, - "This file describe the configuration, it is recommended to edit the relevant *.secret.exs file instead of the others founds in the ``config`` directory. -If you run Pleroma with ``MIX_ENV=prod`` the file is ``prod.secret.exs``, otherwise it is ``dev.secret.exs``.\r\n\r\n" + "This file describe the configuration, it is recommended to edit the relevant `*.secret.exs` file instead of the others founds in the ``config`` directory. \r\n + If you run Pleroma with ``MIX_ENV=prod`` the file is ``prod.secret.exs``, otherwise it is ``dev.secret.exs``.\r\n\r\n" ) for group <- descriptions do @@ -20,7 +21,6 @@ def process(descriptions) do IO.write(file, "## #{inspect(group[:key])}\r\n\r\n") end - IO.write(file, "Type: `#{group[:type]}` \r\n") IO.write(file, "#{group[:description]} \r\n\r\n") for child <- group[:children] do @@ -44,24 +44,36 @@ def process(descriptions) do {:ok, config_path} end + defp print_suggestion(file, suggestion) when is_list(suggestion) do + IO.write(file, " `#{inspect(suggestion)}`\r\n") + end + defp print_suggestion(file, suggestion) when is_function(suggestion) do IO.write(file, " `#{inspect(suggestion.())}`\r\n") end - defp print_suggestion(file, suggestion) do - IO.write(file, " `#{inspect(suggestion)}`\r\n") + defp print_suggestion(file, suggestion, as_list \\ false) do + list_mark = if as_list, do: "*", else: "" + IO.write(file, " #{list_mark} `#{inspect(suggestion)}`\r\n") end - defp print_suggestions(file, suggestions) do - IO.write(file, "Suggestions: \r\n") + defp print_suggestions(_file, nil), do: nil - for suggestion <- suggestions do - print_suggestion(file, suggestion) + defp print_suggestions(file, suggestions) do + IO.write(file, " Suggestions: \r\n") + + if length(suggestions) > 1 do + for suggestion <- suggestions do + print_suggestion(file, suggestion, true) + end + else + print_suggestion(file, List.first(suggestions)) end end defp print_child_header(file, child) do - IO.write(file, "* `#{inspect(child[:key])}`: #{child[:description]} \r\n") - IO.write(file, "Type: `#{inspect(child[:type])}` \r\n") + IO.write(file, "* `#{inspect(child[:key])}` \r\n") + IO.write(file, " #{child[:description]} \r\n") + IO.write(file, " Type: `#{inspect(child[:type])}` \r\n") end end