Using notebooks or Julia markdown with Documenter.jl

General Usage
, , , ,
1

I would like to use notebooks or Julia markdown (jmd) with Documenter.jl similarly to mkdocs-jupyter, but I cannot find any tutorials or examples on how to do so.

My first idea was to use Weave.jl to generate markdown from jmd files. Then, Documenter.jl would do the rest. I believe this would work in production. However, when developing using live reload, I start an endless loop. LiveServer.jl detects a change, it triggers my make.jl script which use weave to generate markdown. LiveServer detects this change, and the cycle repeats. Additionally, having generated files among my other files is perhaps not a good practise either?

Therefore, I thought of weaving into temporary directories (e.g. using mktempdir()). However, Documenter does not recognise files outside the docs folder (see issue #551).

Does anyone have other ideas?

2

Utilize the skip_dirs and skip_files keyword arguments to servedocs, see LiveServer.jl/src/utils.jl at eec3d5b23d16e296ba55c4f99084c1814bee5165 · tlienart/LiveServer.jl · GitHub.

Example usage: Ferrite.jl/docs/liveserver.jl at 241d181490511e67fcb5d723b67ecb1c22cbe363 · Ferrite-FEM/Ferrite.jl · GitHub

1 Like
3

I recently tried to use skip_dirs with a custom Literate.jl combination and got infinite loop anyway. Looking in a code I saw that file watcher does not respect those arguments as can be seen in the code: LiveServer.jl/src/utils.jl at eec3d5b23d16e296ba55c4f99084c1814bee5165 · tlienart/LiveServer.jl · GitHub

A thing that works though is to clean up all generated files before starting the live server as then those are not registered with the file watcher.

4

They might be added to the watcher, but the callback filters them out here: LiveServer.jl/src/utils.jl at eec3d5b23d16e296ba55c4f99084c1814bee5165 · tlienart/LiveServer.jl · GitHub. If you have a MWE where this doesn’t work I can have a look.

1 Like
5

I got skip_dir to work with my setup. The issue was that MacOS file paths are case-insensitive, and I made a mistake in specifying the path. The generated files could be removed just fine; however, the startswith(fp, dir) would always return false :pensive:.