# Literate.jl: how to skip code parsing/testing for quick generation and preview of the documentation?

**URL:** <https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603>\
**Category:** Tooling\
**Tags:** documenter, literate-programming\
**Created:** [April 5, 2021, 9:45am UTC](https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603 "2021-04-05T09:45:48Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [April 5, 2021, 9:45am UTC](https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603/1 "2021-04-05T09:45:48Z")

</div>

I am using [Literate](https://github.com/fredrikekre/Literate.jl) —\> [Documenter](https://github.com/JuliaDocs/Documenter.jl) for the documentation of my package, but the inclusion of some tutorials makes the generation of the documentation taking a while.

Sometimes I would just like to try how the documentation (including the automatic links) is rendered… Is there some keyword I can pass to `Literate.Markdown` to tell it to skip the code evaluation/testing (or perhaps in a preprocess function ???) ? Then I could call my make.jl script with a keyword like “preview” or “quick” to speed up the generation of the documentation.

This is my current `make.jl`:

```julia
using Documenter, Literate, BetaML, Test

push!(LOAD_PATH,"../src/")

const _TUTORIAL_DIR = joinpath(@ __DIR__ , "src", "tutorials")
const _TUTORIAL_SUBDIR = [
    "Getting started",
    "Regression - bike sharing",
    "Classification - cars",
    "Clusterisation - Iris"
]

function link_example(content)
    edit_url = match(r"EditURL = \"(.+?)\"", content)[1]
    footer = match(r"^(---\n\n\*This page was generated using)"m, content)[1]
    content = replace(
        content, footer => "[View this file on Github]($(edit_url)).\n\n" * footer
    )
    return content
end

function _file_list(full_dir, relative_dir, extension)
    return map(
        file -> joinpath(relative_dir, file),
        filter(file -> endswith(file, extension), sort(readdir(full_dir))),
    )
end

"""
    _include_sandbox(filename)
Include the `filename` in a temporary module that acts as a sandbox. (Ensuring
no constants or functions leak into other files.)
"""
function _include_sandbox(filename)
    mod = @eval module $(gensym()) end
    return Base.include(mod, filename)
end

function literate_directory(dir)
    rm.(_file_list(dir, dir, ".md"))
    for filename in _file_list(dir, dir, ".jl")
        # `include` the file to test it before `#src` lines are removed. It is
        # in a testset to isolate local variables between files.
        @testset "$(filename)" begin
            _include_sandbox(filename)
        end
        Literate.markdown(
            filename,
            dir;
            documenter = true,
            postprocess = link_example,
        )
    end
    return nothing
end

literate_directory.(joinpath.(_TUTORIAL_DIR, _TUTORIAL_SUBDIR))

makedocs(sitename="BetaML.jl Documentation",
         authors = "Antonello Lobianco",
         pages = [
            "Index" => "index.md",
            "Perceptron" => "Perceptron.md",
            "Trees" => "Trees.md",
            "Nn" => "Nn.md",
            "Clustering" => "Clustering.md",
            "Utils" => "Utils.md",
            "Tutorials" => map(
                subdir -> subdir => map(
                    file -> joinpath("tutorials", subdir, file),
                    filter(
                        file -> endswith(file, ".md"),
                        sort(readdir(joinpath(_TUTORIAL_DIR, subdir))),
                    ),
                ),
                _TUTORIAL_SUBDIR,
            ),
            "Examples" => "Examples.md"
         ],
         format = Documenter.HTML(prettyurls = false)
)
deploydocs(
    repo = "github.com/sylvaticus/BetaML.jl.git",
)

```

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [April 5, 2021, 10:05am UTC](https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603/2 "2021-04-05T10:05:19Z")

</div>

I did try with `doctest = false` in the (Documenter) `makedocs` function, but without success… it seems the code is parsed and executed in Literate, before reaching Documenter…

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [April 5, 2021, 11:36am UTC](https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603/3 "2021-04-05T11:36:53Z")

</div>

Unless you pass `execute=true` to `Literate.markdown` Literate does not execute any code. By default Literate results in Documenter `@example` blocks though, which are executed by Documenter. Documenter does not have a preview/draft option (might be a good feature request), but you can tell Literate to not generate `@example` blocks using the `codefence` keyword argument. For example, to output generic julia code blocks you can pass

````julia
codefence = "```julia" => "```"

````

to `Literate.markdown`.

* * *

As a sidenote, why do the code take so long? You could probably speed things up a lot by using Revise (unless the time is actually dominated by runtime rather than compile time).

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [April 5, 2021, 11:46am UTC](https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603/4 "2021-04-05T11:46:57Z")

</div>

I added as you suggested the parameter `codefence = "```julia" => "```"` in the `Literate.markdown` call in the make script above, but still the code is computed…

 ![image](https://global.discourse-cdn.com/julialang/original/3X/4/a/4a7fc4f343a9cd1c428cc56819669629e48fbb3b.png)

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [April 5, 2021, 11:49am UTC](https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603/5 "2021-04-05T11:49:48Z")

</div>

Can you link to the repo? I don’t see any code execution from Literate in that screenshot.

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [April 5, 2021, 1:13pm UTC](https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603/6 "2021-04-05T13:13:01Z")

</div>

The repository is here: [https://github.com/sylvaticus/BetaML.jl](https://github.com/sylvaticus/BetaML.jl)  
And, in particular, the documentation is [here](https://sylvaticus.github.io/BetaML.jl/dev) and the make.jl (without yet the `codefence` committed) is [here](https://github.com/sylvaticus/BetaML.jl/blob/master/docs/make.jl).

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [April 5, 2021, 2:09pm UTC](https://discourse.julialang.org/t/literate-jl-how-to-skip-code-parsing-testing-for-quick-generation-and-preview-of-the-documentation/58603/7 "2021-04-05T14:09:04Z")

</div>

Thank you, I solved.

It was due to this:

```julia
"""
    _include_sandbox(filename)
Include the `filename` in a temporary module that acts as a sandbox. (Ensuring
no constants or functions leak into other files.)
"""
function _include_sandbox(filename)
    mod = @eval module $(gensym()) end
    return Base.include(mod, filename)
end
[...]
# `include` the file to test it before `#src` lines are removed. It is
# in a testset to isolate local variables between files.
@testset "$(filename)" begin
     _include_sandbox(filename)
end

```

Actually I understood now that the code was running twice! Once for the above testset, and once as an example block in Documenter.  
By commenting the code above and using the codefence keyword in `Literate.Markdown` I managed to get the documentation buildwithout running the code, thanks.