Using Mermaid with ex_doc?

Questions / Help
1

I saw a few thread about mermaid – it is a markdown way to make some charts and diagrams. I think it can be very useful for documentations. Does anyone know if ex_doc has “hooks” where something like this could be used? I’m not sure if I follow the ex_doc documentation, but hopefully someone knows if this might be possible! Thank you!

1 Like
2

Yes, in mix help docs:

  • :javascript_config_path - Path of an additional JavaScript file to be
    included on all pages to provide up-to-date data for features like the
    version dropdown - See the “Additional JavaScript config” section. Example:
    "../versions.js"

So you can write script that will process Mermaid blocks in your documentation on the FE side. Alternatively you can write use options/custom wrapper for the Markdown parser, so you will be able to statically generate images basing on the returned data.

5 Likes
3

Thank you, I got this to work! I am now noticing however that you cannot use a module’s own functions to generate the @moduledoc because the module has not yet compiled. This makes sense but I am wondering if there might be some tricks to get the module documentation updated.

4

What do you mean? What for you need such behaviour?

5

I think you can generate the @moduledoc as part of @before_compile. The Macro.Env.t term passed into the before_compile callback should have information about what functions exist in the module.

1 Like
6

I will take a look at this more, but I think it won’t work because I want to get the output of the function. I actually need to execute the function.

This maybe answers @hauleth’s question: what Mermaid is helpful for is to diagram relationships between some GenStage modules that are connected with PubSub. So I want to show a diagram for the relationships defined by module A. There is an init function that returns the child specs. I can build a function easily that does Enum.reduce over the list and accumulates the informations that Mermaid is needing to make a chart. Even though this chart really belongs in module A, I have to make the chart in module B because it does something like

defmodule B do
  @moduledoc """
  #{A.init() |> make_mermaid_chart()}
  """
end

I hope that makes sense why I need to build the moduledoc inside module B.

7

Well, if you meant GenStage.init/1 callback then it can return different values depending on passed arguments. So unless you return always the same value, then it is not possible to achieve what you want. If you always return the same value, independently of the argument, then you can do:

defmodule A do
  @init_return …

  @moduledoc """
  #{make_mermaid_chart(@init_return)}
  """

  def init(_), do: @init_return
end
1 Like
8

Yes, I thought about module attributes, but the actual values are more complex (at least right now they are). Sometimes the functions take runtime argument and things like that, so it doesn’t always work inside the module attributes. It is working well now, it is just in a different module.