Document and improve ExDoc usage

[btkostner]

First off, this project is super awesome! I love being able to have always up to date mermaid diagrams for my Ecto schemas.

I am currently using this library to generate mermaid diagrams in ex_doc. I think this usage is pretty common, but it's not documented and the API is a little verbose.

I can get mermaid diagrams outputted like so:

  @moduledoc """
  This is information about our `ATcms.Account` context.

  #{ATcms.Account.UserSchema |> Code.ensure_loaded!() |> then(fn _ -> "" end)}

  ` ` `mermaid
  #{Ecto.ERD.Document.render([ATcms.Account.UserSchema], ".mmd", &Function.identity/1, [])}
  ` ` `
  """

We should document this use case so other people can enjoy the fun! Secondly, it would be awesome to clean up this code and make it easier to use. Something like Ecto.ERD.render([ATcms.Account.UserSchema], ".mmd") that would ensure the code is loaded and render out the modules to mermaid.

[fuelen]

Hi @btkostner

Having a public Ecto.ERD.render is a good idea.

Just want to warn you that such usage adds compile-time dependencies with the schema modules. I'd suggest generating diagrams separately and do not embed them into the code directly. Code compilation is a much more frequent operation than generating docs. So, in your Account context, just insert a link to the markdown file with Mermaid diagram or directly to the generated image and that's it. If you really want to have it in moduledocs, then I'd do this only using some compile-time flag, which would require a new env for docs.

[fuelen]

Now, I'm not sure about exposing a public function for rendering a document in order not to encourage usage in moduledocs. I need other scenarios why public function is needed and not a mix task :)

[btkostner]

So, going against adding a public function in documentation because of the compile errors and all the other issues there. I think the use case still stands (just needs to be implemented differently.) I'd still like a way to render only some modules so I can do it on a per context basis. I can think of:

1. Users writing a mix task that runs the public render function and generates all of the needed files. This can already be done, but it'd be nice to clean up the functions and possibly document this approach.
2. Updating the ecto_erd configuration file to allow multiple renders and specifying which modules to render

[fuelen]

It is already possible to render only some modules by using map_node parameter. The callback function must return nil for modules which must be removed. Multiple renders can be achieved by using multiple configuration files :)