@eval returning @docs blocks don't render as documentation.

[Sam Atman]

I tried doing something like this:

# ```@eval
using Markdown
using MyModule

block = ["```@docs\n"]
push!(block, "MyModule.DocumentedThing\n")
push!(block, "```\n")
return Markdown.parse(join(block))
# ```

Although, of course, the actual code was more complex. The idea was to assure that changes to, in this example, an enum, were always reflected correctly in the documentation.

But this just renders as a block, it isn't interpreted as a @docs block.

[Michael Goerz]

Yeah, that doesn't work. The capabilities of @eval are pretty limited, and don't include "recursive" evaluation. I'm not sure if anything like that would be on any roadmap.

[Sam Atman]

Isn't this more of an order of operations thing? I'm not clear on whether the Markdown package recognizes ```@tag syntax as a valid way to make a codeblock, or if that code is Documenter-specific.

What I thought would happen isn't recursive, although, now that you mention it, it could be used for recursion, however pointless that might be. I figured, if you return a table, Documenter renders the table, so if I return a ```@docs block, it will render the docs block. More of a fixed point than anything.

Is there a way to read in another Markdown file verbatim? Generating the block is easy enough, that logic could dump it into a file which gets read in. Even if that doesn't exist, it's probably easier to add a feature like that, than to code a special-case of certain return values of an eval block. More broadly useful as well.

Furthermore, I don't actually know that the Markdown.MD object contains the information needed to detect it. There's a reference to Markdown syntax extensions in the Julia docs, but I don't know if that's the mechanism Documenter is using for at-blocks.

[Michael Goerz]

I'm not clear on whether the Markdown package recognizes ```@tag syntax as a valid way to make a codeblock, or if that code is Documenter-specific.

It's completely Documenter-specific. Anything with an @ is something that's handled by Documenter.

I figured, if you return a table, Documenter renders the table, so if I return a ```@docs block, it will render the docs block

Yeah, that doesn't work. The @eval block is already a Documenter-specific block. It just gets evaluated (via the stdlib Markdown parser) and the resulting markdown syntax tree gets put into the syntax tree for the page. That's it. There is no further processing.

Hypothetically, Documenter could keep re-processing the syntax tree until it reaches a fix-point, but it's not implemented like that. It might also be tricky to implement: this has the potential for getting caught in an infinite regress.

Is there a way to read in another Markdown file verbatim?

Not if that markdown file contains a @docs block, no. Of course, what you can do is programmatically create a .md file in the docs/src folder, e.g. in your make.jl script before makedocs is called.

There's a reference to Markdown syntax extensions in the Julia docs

Quite honestly, I have no idea what that section of the manual is talking about. It might be something that's out of date (as of Documenter 1.0, which changed a lot of the relevant internals) and should be removed, or at least heavily revised. Maybe @mortenpi can clarify that section.

[Sam Atman]

Thanks for explaining. I don't think what I had in mind is a great use for @eval blocks, I'll close this issue and open a feature issue about inclusion.

[Morten Piibeleht]

There's a reference to Markdown syntax extensions in the Julia docs

Quite honestly, I have no idea what that section of the manual is talking about. It might be something that's out of date (as of Documenter 1.0, which changed a lot of the relevant internals) and should be removed, or at least heavily revised. Maybe @mortenpi can clarify that section.

Pretty sure that references the magic that DocStringExtensions.jl relies on. You can interpolate Julia symbols/expressions into Markdown/docstrings, and then process them.