some changes

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()
         ]
       },
       %{

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]
       )

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)
 

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

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