Skip to content

Commit

Permalink
Fix expansion of link macros when docs are built
Browse files Browse the repository at this point in the history 
with DocumentationGenerator.jl
  • Loading branch information
@fredrikekre
fredrikekre committed Jul 20, 2019
1 parent a8ab34f commit 7af5414
Show file tree
Hide file tree
Showing 3 changed files with 97 additions and 49 deletions.
12 changes: 6 additions & 6 deletions examples/example.jl
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# # **7.** Example
#
#md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__generated/example.ipynb)
#md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__generated/example.ipynb)
#md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/generated/example.ipynb)
#md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/generated/example.ipynb)
#
# This is an example generated with Literate based on this
# source file: [`example.jl`](@__REPO_ROOT_URL__examples/example.jl).
# source file: [`example.jl`](@__REPO_ROOT_URL__/examples/example.jl).
# You are seeing the
#md # HTML-output which Documenter have generated based on a markdown
#md # file generated with Literate. The corresponding notebook
#md # can be viewed in [nbviewer](http://nbviewer.jupyter.org/) here:
#md # [`example.ipynb`](@__NBVIEWER_ROOT_URL__generated/example.ipynb),
#md # [`example.ipynb`](@__NBVIEWER_ROOT_URL__/generated/example.ipynb),
#md # and opened in [binder](https://mybinder.org/) here:
#md # [`example.ipynb`](@__BINDER_ROOT_URL__generated/example.ipynb),
#md # [`example.ipynb`](@__BINDER_ROOT_URL__/generated/example.ipynb),
#nb # generated notebook output. The corresponding markdown (HTML) output
#nb # can be found here: [`example.html`](https://fredrikekre.github.io/Literate.jl/dev/generated/example.html),
# and the plain script output can be found here: [`example.jl`](./example.jl).

# It is recommended to have the [source file](@__REPO_ROOT_URL__examples/example.jl)
# It is recommended to have the [source file](@__REPO_ROOT_URL__/examples/example.jl)
# available when reading this, to better understand how the syntax in the source file
# corresponds to the output you are seeing.

Expand Down
12 changes: 6 additions & 6 deletions src/Literate.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ function replace_default(content, sym;
### replace @__NBVIEWER_ROOT_URL__ to dev or version directory
nbviewer_root_url = "https://nbviewer.jupyter.org/urls/$(base_url)"
push!(repls, "@__NBVIEWER_ROOT_URL__" => nbviewer_root_url)
### replace $__BINDER_ROOT_URL__ to dev or version directory
### replace @__BINDER_ROOT_URL__ to dev or version directory
### TODO: Binder requires files to be in a git repository :(
if match(r"@__BINDER_ROOT_URL__", content) !== nothing
@warn("mybinder.org requires the notebook to be in a git repository, " *
Expand All @@ -196,13 +196,13 @@ function replace_default(content, sym;
### and release folders since these will not change
folder = isempty(travis_tag) ? "dev" : travis_tag
### replace @__REPO_ROOT_URL__ to master/commit
repo_root_url = "https://github.com/$(travis_repo_slug)/blob/$(commit)/"
repo_root_url = "https://github.com/$(travis_repo_slug)/blob/$(commit)"
push!(repls, "@__REPO_ROOT_URL__" => repo_root_url)
### replace @__NBVIEWER_ROOT_URL__ to dev or version directory
nbviewer_root_url = "https://nbviewer.jupyter.org/github/$(travis_repo_slug)/blob/$(branch)/$(folder)/"
nbviewer_root_url = "https://nbviewer.jupyter.org/github/$(travis_repo_slug)/blob/$(branch)/$(folder)"
push!(repls, "@__NBVIEWER_ROOT_URL__" => nbviewer_root_url)
### replace $__BINDER_ROOT_URL__ to dev or version directory
binder_root_url = "https://mybinder.org/v2/gh/$(travis_repo_slug)/$(branch)?filepath=$(folder)/"
### replace @__BINDER_ROOT_URL__ to dev or version directory
binder_root_url = "https://mybinder.org/v2/gh/$(travis_repo_slug)/$(branch)?filepath=$(folder)"
push!(repls, "@__BINDER_ROOT_URL__" => binder_root_url)
else
## Warn about broken link expansions
Expand Down Expand Up @@ -369,7 +369,7 @@ function markdown(inputfile, outputdir; preprocess = identity, postprocess = ide
end
content = """
# ```@meta
# EditURL = "@__REPO_ROOT_URL__$(path)"
# EditURL = "@__REPO_ROOT_URL__/$(path)"
# ```
""" * content
Expand Down
122 changes: 85 additions & 37 deletions test/runtests.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -186,11 +186,13 @@ content = """
#+
end
# name: @__NAME__
# Link to repo root: @__REPO_ROOT_URL__
# Link to nbviewer: @__NBVIEWER_ROOT_URL__
# Link to repo root: @__REPO_ROOT_URL__/file.jl
# Link to nbviewer: @__NBVIEWER_ROOT_URL__/file.jl
# Link to binder: @__BINDER_ROOT_URL__/file.jl
## name: @__NAME__
## Link to repo root: @__REPO_ROOT_URL__
## Link to nbviewer: @__NBVIEWER_ROOT_URL__
## Link to repo root: @__REPO_ROOT_URL__/file.jl
## Link to nbviewer: @__NBVIEWER_ROOT_URL__/file.jl
## Link to binder: @__BINDER_ROOT_URL__/file.jl
# PLACEHOLDER1
# PLACEHOLDER2
Expand Down Expand Up @@ -253,8 +255,9 @@ content = """
end
# name: inputfile
# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/
# Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/
# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/file.jl
# Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/file.jl
# Link to binder: https://mybinder.org/v2/gh/fredrikekre/Literate.jl/gh-pages?filepath=v1.2.0/file.jl
# PLACEHOLDER3
# PLACEHOLDER4
Expand All @@ -279,10 +282,21 @@ content = """
script = read(joinpath(outdir, "inputfile.jl"), String)
@test occursin("fredrikekre/Literate.jl/blob/gh-pages/dev/", script)

# building under DocumentationGenerator.jl
withenv("DOCUMENTATIONGENERATOR" => "true",
"DOCUMENTATIONGENERATOR_BASE_URL" => "pkg.julialang.org/docs/Literate/XPnWG/1.2.0") do
@test_logs((:warn, r"mybinder.org"), match_mode=:any,
Literate.script(inputfile, outdir))
end
script = read(joinpath(outdir, "inputfile.jl"), String)
@test occursin("jupyter.org/urls/pkg.julialang.org/docs/Literate/XPnWG/1.2.0/file.jl", script)
@test_broken occursin("https://github.com/fredrikekre/Literate.jl/blob/master/file.jl", script)

# pre- and post-processing
Literate.script(inputfile, outdir,
preprocess = x -> replace(x, "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = x -> replace(x, "PLACEHOLDER4" => "4REDLOHECALP"))
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.script(inputfile, outdir,
preprocess = x -> replace(x, "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = x -> replace(x, "PLACEHOLDER4" => "4REDLOHECALP")))
script = read(joinpath(outdir, "inputfile.jl"), String)
@test !occursin("PLACEHOLDER1", script)
@test !occursin("PLACEHOLDER2", script)
Expand All @@ -292,14 +306,16 @@ content = """
@test occursin("4REDLOHECALP", script)

# name
Literate.script(inputfile, outdir, name = "foobar")
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.script(inputfile, outdir, name = "foobar"))
script = read(joinpath(outdir, "foobar.jl"), String)
@test occursin("name: foobar", script)
@test !occursin("name: inputfile", script)
@test !occursin("name: @__NAME__", script)

# keep_comments
Literate.script(inputfile, outdir, keep_comments = true)
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.script(inputfile, outdir, keep_comments = true))
script = read(joinpath(outdir, "inputfile.jl"), String)
@test occursin("# # Example", script)
@test occursin("# foo, bar", script)
Expand Down Expand Up @@ -369,13 +385,15 @@ end
```
name: inputfile
Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/
Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/
Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/file.jl
Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/file.jl
Link to binder: https://mybinder.org/v2/gh/fredrikekre/Literate.jl/gh-pages?filepath=v1.2.0/file.jl
```@example inputfile
# name: inputfile
# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/
# Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/
# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/file.jl
# Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/file.jl
# Link to binder: https://mybinder.org/v2/gh/fredrikekre/Literate.jl/gh-pages?filepath=v1.2.0/file.jl
```
PLACEHOLDER1
Expand Down Expand Up @@ -419,10 +437,21 @@ end
markdown = read(joinpath(outdir, "inputfile.md"), String)
@test occursin("fredrikekre/Literate.jl/blob/gh-pages/dev/", markdown)

# building under DocumentationGenerator.jl
withenv("DOCUMENTATIONGENERATOR" => "true",
"DOCUMENTATIONGENERATOR_BASE_URL" => "pkg.julialang.org/docs/Literate/XPnWG/1.2.0") do
@test_logs((:warn, r"mybinder.org"), match_mode=:any,
Literate.markdown(inputfile, outdir))
end
markdown = read(joinpath(outdir, "inputfile.md"), String)
@test occursin("jupyter.org/urls/pkg.julialang.org/docs/Literate/XPnWG/1.2.0/file.jl", markdown)
@test_broken occursin("https://github.com/fredrikekre/Literate.jl/blob/master/file.jl", markdown)

# pre- and post-processing
Literate.markdown(inputfile, outdir,
preprocess = x -> replace(replace(x, "PLACEHOLDER1" => "1REDLOHECALP"), "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = x -> replace(replace(x, "PLACEHOLDER2" => "2REDLOHECALP"), "PLACEHOLDER4" => "4REDLOHECALP"))
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.markdown(inputfile, outdir,
preprocess = x -> replace(replace(x, "PLACEHOLDER1" => "1REDLOHECALP"), "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = x -> replace(replace(x, "PLACEHOLDER2" => "2REDLOHECALP"), "PLACEHOLDER4" => "4REDLOHECALP")))
markdown = read(joinpath(outdir, "inputfile.md"), String)
@test !occursin("PLACEHOLDER1", markdown)
@test !occursin("PLACEHOLDER2", markdown)
Expand All @@ -434,22 +463,25 @@ end
@test occursin("4REDLOHECALP", markdown)

# documenter = false
Literate.markdown(inputfile, outdir, documenter = false)
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.markdown(inputfile, outdir, documenter = false))
markdown = read(joinpath(outdir, "inputfile.md"), String)
@test occursin("```julia", markdown)
@test !occursin("```@example", markdown)
@test !occursin("continued = true", markdown)
@test !occursin("EditURL", markdown)

# codefence
Literate.markdown(inputfile, outdir, codefence = "```c" => "```")
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.markdown(inputfile, outdir, codefence = "```c" => "```"))
markdown = read(joinpath(outdir, "inputfile.md"), String)
@test occursin("```c", markdown)
@test !occursin("```@example", markdown)
@test !occursin("```julia", markdown)

# name
Literate.markdown(inputfile, outdir, name = "foobar")
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.markdown(inputfile, outdir, name = "foobar"))
markdown = read(joinpath(outdir, "foobar.md"), String)
@test occursin("```@example foobar", markdown)
@test !occursin("```@example inputfile", markdown)
Expand Down Expand Up @@ -545,16 +577,18 @@ end
"""
"source": [
"name: inputfile\\n",
"Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/\\n",
"Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/"
"Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/file.jl\\n",
"Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/file.jl\\n",
"Link to binder: https://mybinder.org/v2/gh/fredrikekre/Literate.jl/gh-pages?filepath=v1.2.0/file.jl"
]
""",

"""
"source": [
"# name: inputfile\\n",
"# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/\\n",
"# Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/"
"# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/file.jl\\n",
"# Link to nbviewer: https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/v1.2.0/file.jl\\n",
"# Link to binder: https://mybinder.org/v2/gh/fredrikekre/Literate.jl/gh-pages?filepath=v1.2.0/file.jl"
]
""",

Expand Down Expand Up @@ -633,6 +667,16 @@ end
notebook = read(joinpath(outdir, "inputfile.ipynb"), String)
@test occursin("fredrikekre/Literate.jl/blob/gh-pages/dev/", notebook)

# building under DocumentationGenerator.jl
withenv("DOCUMENTATIONGENERATOR" => "true",
"DOCUMENTATIONGENERATOR_BASE_URL" => "pkg.julialang.org/docs/Literate/XPnWG/1.2.0") do
@test_logs((:warn, r"mybinder.org"), match_mode=:any,
Literate.notebook(inputfile, outdir, execute = false))
end
notebook = read(joinpath(outdir, "inputfile.ipynb"), String)
@test occursin("jupyter.org/urls/pkg.julialang.org/docs/Literate/XPnWG/1.2.0/file.jl", notebook)
@test_broken occursin("https://github.com/fredrikekre/Literate.jl/blob/master/file.jl", notebook)

# pre- and post-processing
function post(nb)
for cell in nb["cells"]
Expand All @@ -643,9 +687,10 @@ end
end
return nb
end
Literate.notebook(inputfile, outdir, execute = false,
preprocess = x -> replace(replace(x, "PLACEHOLDER1" => "1REDLOHECALP"), "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = post)
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.notebook(inputfile, outdir, execute = false,
preprocess = x -> replace(replace(x, "PLACEHOLDER1" => "1REDLOHECALP"), "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = post))
notebook = read(joinpath(outdir, "inputfile.ipynb"), String)
@test !occursin("PLACEHOLDER1", notebook)
@test !occursin("PLACEHOLDER2", notebook)
Expand All @@ -657,20 +702,23 @@ end
@test occursin("4REDLOHECALP", notebook)

# documenter = false
Literate.notebook(inputfile, outdir, documenter = false, execute = false)
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.notebook(inputfile, outdir, documenter = false, execute = false))
notebook = read(joinpath(outdir, "inputfile.ipynb"), String)
@test occursin("# [Example](@id example-id", notebook)
@test occursin("[foo](@ref), [bar](@ref bbaarr)", notebook)

# name
Literate.notebook(inputfile, outdir, name = "foobar", execute = false)
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.notebook(inputfile, outdir, name = "foobar", execute = false))
notebook = read(joinpath(outdir, "foobar.ipynb"), String)
@test occursin("name: foobar", notebook)
@test !occursin("name: inputfile", notebook)
@test !occursin("name: @__NAME__", notebook)

# execute = true
Literate.notebook(inputfile, outdir)
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.notebook(inputfile, outdir))
expected_outputs = rstrip.((
"""
"cells": [
Expand Down Expand Up @@ -706,12 +754,12 @@ end

# test error when executing notebook
write(inputfile, "for i in 1:10\n println(i)")
r = try
Literate.notebook(inputfile, outdir)
catch err
@info "^^ the above error log message is expected ^^"
err
end
r = @test_logs((:error, r"error when executing"), match_mode=:any,
try
Literate.notebook(inputfile, outdir)
catch err
err
end)
@test isa(r, ErrorException)
@test occursin("when executing the following code block", r.msg)

Expand Down

0 comments on commit 7af5414

Please sign in to comment.