Odd doctest to html docs formatting

Just some odd behaviour between iex> , doctest and I think :ex_doc

Here is a simple module snippet…

@doc """
  Function 'subtract' takes 2 args and returns answer.

  ## Example

  iex> MyProject.subtract(10, 5) == 5
  true
  """

  def subtract(a, b) do
    a - b
  end
iex> iex(4)> MyProject.subtract(10, 5) == 5       
true

So all is as expected here. Doctest builds OK too.

But, mix docs builds this …

Example

iex>  MyProject.subtract(10, 5) == 5 true

Of course, this is a silly formatting gripe but I don’t understand why the answer, is being appended to the same line ???

I’m very new to this so may have missed something super basic of course.

I’m not sure if this’ll fix the issue, but I believe you’re supposed to indent 4 spaces for doc tests. This has to do with markdown formatting, where it’s not seen as a code block unless it is indented or has code fences (three backticks).

So:

  @doc """
  Function 'subtract' takes 2 args and returns answer.

  ## Example

      iex> MyProject.subtract(10, 5) == 5
      true
  """

  def subtract(a, b) do
    a - b
  end
1 Like

That’s what I was thinking too.

However, I am actually 4 spaces indented and…

$ mix test

Finished in 0.07 seconds
2 doctests, 2 tests, 0 failures

Randomized with seed 816823

Clearly I can go to doc/xyz.html and change a few

tags to clean up the formatting but it’s a pain each time i do mix docs

OK, I did indeed shift the actual example iex> stuff 4 ‘further spaces’ indented.
Now it works…

Nice one but still leaves me baffled as to why I got clean builds with incorrect formatting ?

Many thanks anyway.

1 Like

I don’t think doctests care about the format. I think they just look for a line starting with iex> and then take every line after that not separated by a space and assume it’s code. Only the docs would care about the format.

1 Like

Well hopefully I have it sorted now and can move onto writing doctest stuff into my other modules.

1 Like

You can also use GitHub “fenced” syntax like:

```
iex> MyProject.subtract(10, 5) == 5
true
```

In the docs. That is why doctest looks for any line that starts with iex>.

3 Likes