Handling of custom types as docstrings

[zwwi]

This issue was asked at discourse

It can be reproduced by
git clone https://github.com/JuliaPy/PyPlot.jl
then create a doc dir with the following make.jl

using Documenter, PyPlot

makedocs(;
    modules=[PyPlot],
    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
    pages = ["Home" => "index.md" ]
)

Project.toml:

[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
PyPlot = "d330b81b-6aea-500a-939a-2ce795aea3ee"

and src/index.md:

CurrentModule = PyPlot
```

# PyPlot.jl
    
```@index
```

```@autodocs
Modules = [PyPlot]

Then julia make.jl gives the following error message:

[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
ERROR: LoadError: AssertionError: md isa Markdown.MD
Stacktrace:
...

[mortenpi]

This is an interesting case. So, LazyHelp is a custom type that gets attached as the docstring object where normally you'd have a Markdown.MD object. The simplest MWE would be:

using Documenter
module Foos
    struct Foo end
    function foo end
    @doc Foo() foo
end
makedocs(modules=[Foos], sitename=".")

It's not immediately clear how we should handle it though. Documenter can't really automatically handle arbitrary types. So we'd need some public API where the user can provide a way to convert from the custom type to Markdown AST.

[fredrikekre]

Perhaps the LazyHelp type should just implement show(io::IO, ::MIME"text/markdown", lh::LazyHelp) and Documenter can use that? That IMO makes more sense than e.g. convert(MD, lh::LazyHelp).

For Documenter this would just then be to, for any non-markdown docs, show as markdown and then parse.

[mortenpi]

If I read it correctly, the REPL uses print to get the text representation. Which, of course, should fall back.. to the MIME"text/plain" method of show? So would it make sense to do this in Documenter (in slight Julia pseudocode):

if showable(MIME("text/markdown"), docstr)
    Markdown.parse(show(MIME("text/markdown"), docstr))
else
    Markdown.Code(show(MIME("text/plain"), docstr))
end

[sethaxen]

I had the same issue as @zwwi doing what sounds like almost the same thing: adapting LazyHelper to generate docstrings for a function wrapping a Python function without requiring that the Python module be available during precompilation. Is there an alternative way to do this?

[AtsushiSakai]

I had the same issue for Python functions wrapper with PyCall and LazyHelper. My workaround is doctest = false in makedocs.