Merge branch 'bugfix/docs-formatting' into 'develop'

Improve generated docs formatting

See merge request pleroma/pleroma!1688

lib/pleroma/docs/markdown.ex

@@ -23,7 +23,7 @@ def process(descriptions) do
 
       IO.write(file, "#{group[:description]}\n")
 
-      for child <- group[:children] do
+      for child <- group[:children] || [] do
         print_child_header(file, child)
 
         print_suggestions(file, child[:suggestions])
@@ -44,6 +44,17 @@ def process(descriptions) do
     {:ok, config_path}
   end
 
+  defp print_child_header(file, %{key: key, type: type, description: description} = _child) do
+    IO.write(
+      file,
+      "- `#{inspect(key)}` (`#{inspect(type)}`): #{description}  \n"
+    )
+  end
+
+  defp print_child_header(file, %{key: key, type: type} = _child) do
+    IO.write(file, "- `#{inspect(key)}` (`#{inspect(type)}`)  \n")
+  end
+
   defp print_suggestion(file, suggestion) when is_list(suggestion) do
     IO.write(file, "  `#{inspect(suggestion)}`\n")
   end
@@ -59,20 +70,19 @@ defp print_suggestion(file, suggestion, as_list \\ false) do
 
   defp print_suggestions(_file, nil), do: nil
 
-  defp print_suggestions(file, suggestions) do
-    IO.write(file, "Suggestions:\n")
+  defp print_suggestions(_file, ""), do: nil
 
+  defp print_suggestions(file, suggestions) do
     if length(suggestions) > 1 do
+      IO.write(file, "Suggestions:\n")
+
       for suggestion <- suggestions do
         print_suggestion(file, suggestion, true)
       end
     else
+      IO.write(file, "  Suggestion: ")
+
       print_suggestion(file, List.first(suggestions))
     end
   end
-
-  defp print_child_header(file, child) do
-    IO.write(file, "- `#{inspect(child[:key])}` -`#{inspect(child[:type])}`  \n")
-    IO.write(file, "#{child[:description]}  \n")
-  end
 end

mix.exs

@@ -174,7 +174,8 @@ defp aliases do
       "ecto.rollback": ["pleroma.ecto.rollback"],
       "ecto.setup": ["ecto.create", "ecto.migrate", "run priv/repo/seeds.exs"],
       "ecto.reset": ["ecto.drop", "ecto.setup"],
-      test: ["ecto.create --quiet", "ecto.migrate", "test"]
+      test: ["ecto.create --quiet", "ecto.migrate", "test"],
+      docs: ["pleroma.docs", "docs"]
     ]
   end