Can documenter insert (embed) examples from a file to a page code block?

Tooling
1

I would like to add some full-feature examples on my package documentation, but rather than copy/pasting in the example block I would like to keep each example on its own file.

In general markdown this is not possible, but maybe using Documenter it is ?? :slight_smile:

2

There is an open issue for this kind of feature. You have a few options for a workaround though:

  1. As suggested by Kristoffer, you can do something like

    ````@eval
Markdown.parse("""
```julia
$(readstring("PATH_TO_FILE"))
```
""")
````

  2. Another option is to use Literate.jl to convert the script into a .md file for Documenter. You can look at how examples/example.jl is included in the Literate docs (basically, you just need to add a Literate.markdown call to docs/make.jl.

  3. Finally, you can always do your own pre-processing or generation of the .md files in docs/make.jl.

1 Like
3

JuMP embeds all of our examples with literate. It works excellently.

See
https://jump.dev/JuMP.jl/dev/tutorials/Getting%20started/getting_started_with_JuMP/

There is a link at the bottom to the source file

5 Likes