r
/
Literate.jl
mirror of https://github.com/fredrikekre/Literate.jl
1
0
Fork 0
Code Releases Activity
Browse Source

Fix expansion of link macros when docs are built 

with DocumentationGenerator.jl
pull/72/head
Fredrik Ekre 6 years ago
parent
a8ab34fc2d
commit
7af5414616
3 changed files with 97 additions and 49 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 12
      examples/example.jl
  2. 12
      src/Literate.jl
  3. 104
      test/runtests.jl

12
examples/example.jl
Unescape View File

@ -1,22 +1,22 @@
# # **7.** Example # # **7.** Example
# #
#md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_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) #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 # 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 # You are seeing the
#md # HTML-output which Documenter have generated based on a markdown #md # HTML-output which Documenter have generated based on a markdown
#md # file generated with Literate. The corresponding notebook #md # file generated with Literate. The corresponding notebook
#md # can be viewed in [nbviewer](http://nbviewer.jupyter.org/) here: #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 # 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 # 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), #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). # 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 # available when reading this, to better understand how the syntax in the source file
# corresponds to the output you are seeing. # corresponds to the output you are seeing.

12
src/Literate.jl
Unescape View File

@ -181,7 +181,7 @@ function replace_default(content, sym;
### replace @__NBVIEWER_ROOT_URL__ to dev or version directory ### replace @__NBVIEWER_ROOT_URL__ to dev or version directory
nbviewer_root_url = "https://nbviewer.jupyter.org/urls/$(base_url)" nbviewer_root_url = "https://nbviewer.jupyter.org/urls/$(base_url)"
push!(repls, "@__NBVIEWER_ROOT_URL__" => nbviewer_root_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 :( ### TODO: Binder requires files to be in a git repository :(
if match(r"@__BINDER_ROOT_URL__", content) !== nothing if match(r"@__BINDER_ROOT_URL__", content) !== nothing
@warn("mybinder.org requires the notebook to be in a git repository, " * @warn("mybinder.org requires the notebook to be in a git repository, " *
@ -196,13 +196,13 @@ function replace_default(content, sym;
### and release folders since these will not change ### and release folders since these will not change
folder = isempty(travis_tag) ? "dev" : travis_tag folder = isempty(travis_tag) ? "dev" : travis_tag
### replace @__REPO_ROOT_URL__ to master/commit ### 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) push!(repls, "@__REPO_ROOT_URL__" => repo_root_url)
### replace @__NBVIEWER_ROOT_URL__ to dev or version directory ### 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) 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
binder_root_url = "https://mybinder.org/v2/gh/$(travis_repo_slug)/$(branch)?filepath=$(folder)/" binder_root_url = "https://mybinder.org/v2/gh/$(travis_repo_slug)/$(branch)?filepath=$(folder)"
push!(repls, "@__BINDER_ROOT_URL__" => binder_root_url) push!(repls, "@__BINDER_ROOT_URL__" => binder_root_url)
else else
## Warn about broken link expansions ## Warn about broken link expansions
@ -369,7 +369,7 @@ function markdown(inputfile, outputdir; preprocess = identity, postprocess = ide
end end
content = """ content = """
# ```@meta # ```@meta
# EditURL = "@__REPO_ROOT_URL__$(path)" # EditURL = "@__REPO_ROOT_URL__/$(path)"
# ``` # ```
""" * content """ * content

104
test/runtests.jl
Unescape View File

@ -186,11 +186,13 @@ content = """
#+ #+
end end
# name: @__NAME__ # name: @__NAME__
# Link to repo root: @__REPO_ROOT_URL__ # Link to repo root: @__REPO_ROOT_URL__/file.jl
# Link to nbviewer: @__NBVIEWER_ROOT_URL__ # Link to nbviewer: @__NBVIEWER_ROOT_URL__/file.jl
# Link to binder: @__BINDER_ROOT_URL__/file.jl
## name: @__NAME__ ## name: @__NAME__
## Link to repo root: @__REPO_ROOT_URL__ ## Link to repo root: @__REPO_ROOT_URL__/file.jl
## Link to nbviewer: @__NBVIEWER_ROOT_URL__ ## Link to nbviewer: @__NBVIEWER_ROOT_URL__/file.jl
## Link to binder: @__BINDER_ROOT_URL__/file.jl
# PLACEHOLDER1 # PLACEHOLDER1
# PLACEHOLDER2 # PLACEHOLDER2
@ -253,8 +255,9 @@ content = """
end end
# name: inputfile # name: inputfile
# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/ # 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/ # 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 # PLACEHOLDER3
# PLACEHOLDER4 # PLACEHOLDER4
@ -279,10 +282,21 @@ content = """
script = read(joinpath(outdir, "inputfile.jl"), String) script = read(joinpath(outdir, "inputfile.jl"), String)
@test occursin("fredrikekre/Literate.jl/blob/gh-pages/dev/", script) @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 # pre- and post-processing
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.script(inputfile, outdir, Literate.script(inputfile, outdir,
preprocess = x -> replace(x, "PLACEHOLDER3" => "3REDLOHECALP"), preprocess = x -> replace(x, "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = x -> replace(x, "PLACEHOLDER4" => "4REDLOHECALP")) postprocess = x -> replace(x, "PLACEHOLDER4" => "4REDLOHECALP")))
script = read(joinpath(outdir, "inputfile.jl"), String) script = read(joinpath(outdir, "inputfile.jl"), String)
@test !occursin("PLACEHOLDER1", script) @test !occursin("PLACEHOLDER1", script)
@test !occursin("PLACEHOLDER2", script) @test !occursin("PLACEHOLDER2", script)
@ -292,14 +306,16 @@ content = """
@test occursin("4REDLOHECALP", script) @test occursin("4REDLOHECALP", script)
# name # 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) script = read(joinpath(outdir, "foobar.jl"), String)
@test occursin("name: foobar", script) @test occursin("name: foobar", script)
@test !occursin("name: inputfile", script) @test !occursin("name: inputfile", script)
@test !occursin("name: @__NAME__", script) @test !occursin("name: @__NAME__", script)
# keep_comments # 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) script = read(joinpath(outdir, "inputfile.jl"), String)
@test occursin("# # Example", script) @test occursin("# # Example", script)
@test occursin("# foo, bar", script) @test occursin("# foo, bar", script)
@ -369,13 +385,15 @@ end
``` ```
name: inputfile name: inputfile
Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/ 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/ 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 ```@example inputfile
# name: inputfile # name: inputfile
# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/ # 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/ # 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 PLACEHOLDER1
@ -419,10 +437,21 @@ end
markdown = read(joinpath(outdir, "inputfile.md"), String) markdown = read(joinpath(outdir, "inputfile.md"), String)
@test occursin("fredrikekre/Literate.jl/blob/gh-pages/dev/", markdown) @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 # pre- and post-processing
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.markdown(inputfile, outdir, Literate.markdown(inputfile, outdir,
preprocess = x -> replace(replace(x, "PLACEHOLDER1" => "1REDLOHECALP"), "PLACEHOLDER3" => "3REDLOHECALP"), preprocess = x -> replace(replace(x, "PLACEHOLDER1" => "1REDLOHECALP"), "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = x -> replace(replace(x, "PLACEHOLDER2" => "2REDLOHECALP"), "PLACEHOLDER4" => "4REDLOHECALP")) postprocess = x -> replace(replace(x, "PLACEHOLDER2" => "2REDLOHECALP"), "PLACEHOLDER4" => "4REDLOHECALP")))
markdown = read(joinpath(outdir, "inputfile.md"), String) markdown = read(joinpath(outdir, "inputfile.md"), String)
@test !occursin("PLACEHOLDER1", markdown) @test !occursin("PLACEHOLDER1", markdown)
@test !occursin("PLACEHOLDER2", markdown) @test !occursin("PLACEHOLDER2", markdown)
@ -434,7 +463,8 @@ end
@test occursin("4REDLOHECALP", markdown) @test occursin("4REDLOHECALP", markdown)
# documenter = false # 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) markdown = read(joinpath(outdir, "inputfile.md"), String)
@test occursin("```julia", markdown) @test occursin("```julia", markdown)
@test !occursin("```@example", markdown) @test !occursin("```@example", markdown)
@ -442,14 +472,16 @@ end
@test !occursin("EditURL", markdown) @test !occursin("EditURL", markdown)
# codefence # 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) markdown = read(joinpath(outdir, "inputfile.md"), String)
@test occursin("```c", markdown) @test occursin("```c", markdown)
@test !occursin("```@example", markdown) @test !occursin("```@example", markdown)
@test !occursin("```julia", markdown) @test !occursin("```julia", markdown)
# name # 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) markdown = read(joinpath(outdir, "foobar.md"), String)
@test occursin("```@example foobar", markdown) @test occursin("```@example foobar", markdown)
@test !occursin("```@example inputfile", markdown) @test !occursin("```@example inputfile", markdown)
@ -545,16 +577,18 @@ end
""" """
"source": [ "source": [
"name: inputfile\\n", "name: inputfile\\n",
"Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/\\n", "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/" "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": [ "source": [
"# name: inputfile\\n", "# name: inputfile\\n",
"# Link to repo root: https://github.com/fredrikekre/Literate.jl/blob/master/\\n", "# 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/" "# 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"
] ]
""", """,
@ -633,6 +667,16 @@ end
notebook = read(joinpath(outdir, "inputfile.ipynb"), String) notebook = read(joinpath(outdir, "inputfile.ipynb"), String)
@test occursin("fredrikekre/Literate.jl/blob/gh-pages/dev/", notebook) @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 # pre- and post-processing
function post(nb) function post(nb)
for cell in nb["cells"] for cell in nb["cells"]
@ -643,9 +687,10 @@ end
end end
return nb return nb
end end
@test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.notebook(inputfile, outdir, execute = false, Literate.notebook(inputfile, outdir, execute = false,
preprocess = x -> replace(replace(x, "PLACEHOLDER1" => "1REDLOHECALP"), "PLACEHOLDER3" => "3REDLOHECALP"), preprocess = x -> replace(replace(x, "PLACEHOLDER1" => "1REDLOHECALP"), "PLACEHOLDER3" => "3REDLOHECALP"),
postprocess = post) postprocess = post))
notebook = read(joinpath(outdir, "inputfile.ipynb"), String) notebook = read(joinpath(outdir, "inputfile.ipynb"), String)
@test !occursin("PLACEHOLDER1", notebook) @test !occursin("PLACEHOLDER1", notebook)
@test !occursin("PLACEHOLDER2", notebook) @test !occursin("PLACEHOLDER2", notebook)
@ -657,20 +702,23 @@ end
@test occursin("4REDLOHECALP", notebook) @test occursin("4REDLOHECALP", notebook)
# documenter = false # 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) notebook = read(joinpath(outdir, "inputfile.ipynb"), String)
@test occursin("# [Example](@id example-id", notebook) @test occursin("# [Example](@id example-id", notebook)
@test occursin("[foo](@ref), [bar](@ref bbaarr)", notebook) @test occursin("[foo](@ref), [bar](@ref bbaarr)", notebook)
# name # 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) notebook = read(joinpath(outdir, "foobar.ipynb"), String)
@test occursin("name: foobar", notebook) @test occursin("name: foobar", notebook)
@test !occursin("name: inputfile", notebook) @test !occursin("name: inputfile", notebook)
@test !occursin("name: @__NAME__", notebook) @test !occursin("name: @__NAME__", notebook)
# execute = true # execute = true
Literate.notebook(inputfile, outdir) @test_logs((:warn, r"expansion of"), match_mode=:any,
Literate.notebook(inputfile, outdir))
expected_outputs = rstrip.(( expected_outputs = rstrip.((
""" """
"cells": [ "cells": [
@ -706,12 +754,12 @@ end
# test error when executing notebook # test error when executing notebook
write(inputfile, "for i in 1:10\n println(i)") write(inputfile, "for i in 1:10\n println(i)")
r = try r = @test_logs((:error, r"error when executing"), match_mode=:any,
try
Literate.notebook(inputfile, outdir) Literate.notebook(inputfile, outdir)
catch err catch err
@info "^^ the above error log message is expected ^^"
err err
end end)
@test isa(r, ErrorException) @test isa(r, ErrorException)
@test occursin("when executing the following code block", r.msg) @test occursin("when executing the following code block", r.msg)

Write Preview
Loading…
Cancel
Save