Multiple environments in Documenter

General Usage
, ,
1

Hi!
For KernelFunctions.jl, we are generating examples via Literate.jl, pass them to Documenter.jl and we would like that each example has its own environment/Project.toml.

The problem of course is that when running makedocs it is not possible to use different environments. When activating one environment after another, the packages would stay loaded and this would create some clash.
Has anyone tried to solve this or even succeeded?

Thanks!

2

You can run each example in a separate julia process where you set up the environment you need.

3

That’s what we had in mind, but it’s quite unclear how one should go about it.
Each “example” process should call makedocs specifically on the example.md generated by Literate and then there would be one common makedocs call to build the rest of the docs and combine it with the examples which have now been run?
I could not find anything on how to fine tune Documenter generation in the docs.

4

Why do you want more than one makedocs call? I thought only the calls to Literate would have to be in their own environments?

This is what I had in mind:

$ tree .
.
|-- docs
|   |-- make.jl
|   |-- Manifest.toml
|   |-- Project.toml # Documenter, Literate, ...
|   `-- src
|       `-- literate-src
|           |-- example-1
|           |   |-- Manifest.toml
|           |   `-- Project.toml # Example-1 specific deps
|           `-- example-2
|               |-- Manifest.toml
|               `-- Project.toml # Example-2 specific deps
|-- Manifest.toml
|-- Project.toml
`-- src
    `-- KernelFunctions.jl

And then in make.jl you would use something like

using Documenter

# Run Literate examples in their own processes
examples = joinpath(@__DIR__, "src", "literate-src")
cmd = Base.julia_cmd()
docs_env = @__DIR__
for example in readdir(examples; join=true)
    load_path = "$(example):$(docs_env)"
    code = """
    using Literate
    Literate.markdown(...)
    """
    run(addenv(`$(cmd) -e $(code)`, Dict("JULIA_LOAD_PATH" => load_path)))
end


makedocs(
    # ...
)

deploydocs(
    # ...
)
5

Thanks! That’s already one important step, but this does not solve the whole problem.
The output for the code with the Literate.markdown() command will be @example blocks right?
And these blocks will be effectively run by Documenter (via makedocs), but there will be the same problem of having only one process to run them all.

6

Ah okay. You can actually execute using Literate though (pass execute=true).

1 Like
7

Thanks that’s exactly what I was missing!
Thanks again for you amazing work on Literate :slight_smile: