Skip to content

Commit 4e71b15

Browse files
fredrikekrefredrikekre
authored
Make URLs configurable, fixes #79. (#84)
1 parent 0f9e836 commit 4e71b15

3 files changed

Lines changed: 252 additions & 171 deletions

File tree

‎docs/Manifest.toml‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,9 @@ version = "1.1.0"
3434

3535
[[DataStructures]]
3636
deps = ["InteractiveUtils", "OrderedCollections"]
37-
git-tree-sha1 = "1fe8fad5fc84686dcbc674aa255bc867a64f8132"
37+
git-tree-sha1 = "a1b652fb77ae8ca7ea328fa7ba5aa151036e5c10"
3838
uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
39-
version = "0.17.5"
39+
version = "0.17.6"
4040

4141
[[Dates]]
4242
deps = ["Printf"]
@@ -58,9 +58,9 @@ version = "0.8.1"
5858

5959
[[Documenter]]
6060
deps = ["Base64", "Dates", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
61-
git-tree-sha1 = "0e52069b5970cb27234153f578227947565152c5"
61+
git-tree-sha1 = "7f6ad432deb42aa108bc79205ee96d28724b084f"
6262
uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
63-
version = "0.24.0"
63+
version = "0.24.1"
6464

6565
[[FFMPEG]]
6666
deps = ["BinaryProvider", "Libdl"]
@@ -74,10 +74,10 @@ uuid = "53c48c17-4a7d-5ca2-90c5-79b7896eea93"
7474
version = "0.6.1"
7575

7676
[[GR]]
77-
deps = ["Base64", "DelimitedFiles", "LinearAlgebra", "Pkg", "Printf", "Random", "Serialization", "Sockets", "Test"]
78-
git-tree-sha1 = "2b29ed254586324366e43f4283880978e6956d1f"
77+
deps = ["Base64", "DelimitedFiles", "LinearAlgebra", "Printf", "Random", "Serialization", "Sockets", "Test"]
78+
git-tree-sha1 = "c690c2ab22ac9ee323d9966deae61a089362b25c"
7979
uuid = "28b8d3ca-fb5f-59d9-8090-bfdbd6d07a71"
80-
version = "0.42.0"
80+
version = "0.44.0"
8181

8282
[[GeometryTypes]]
8383
deps = ["ColorTypes", "FixedPointNumbers", "IterTools", "LinearAlgebra", "StaticArrays"]
@@ -173,9 +173,9 @@ version = "0.6.1"
173173

174174
[[Plots]]
175175
deps = ["Base64", "Contour", "Dates", "FFMPEG", "FixedPointNumbers", "GR", "GeometryTypes", "JSON", "LinearAlgebra", "Measures", "NaNMath", "Pkg", "PlotThemes", "PlotUtils", "Printf", "REPL", "Random", "RecipesBase", "Reexport", "Requires", "Showoff", "SparseArrays", "Statistics", "StatsBase", "UUIDs"]
176-
git-tree-sha1 = "0d7cf139b508defb467ac4fd655f4bd4d92f30cf"
176+
git-tree-sha1 = "11c75a31269c1c64790e7cb910346f64cd4440c1"
177177
uuid = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
178-
version = "0.27.0"
178+
version = "0.27.1"
179179

180180
[[Printf]]
181181
deps = ["Unicode"]

‎src/Literate.jl‎

Lines changed: 58 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -175,56 +175,16 @@ function replace_default(content, sym;
175175
push!(repls, "@__NAME__" => config["name"]::String)
176176

177177
# fix links
178+
178179
if get(ENV, "DOCUMENTATIONGENERATOR", "") == "true"
179180
## DocumentationGenerator.jl
180-
### URL to the root of the deployment, see
181-
### https://github.com/JuliaDocs/DocumentationGenerator.jl/pull/76
182181
base_url = get(ENV, "DOCUMENTATIONGENERATOR_BASE_URL", "DOCUMENTATIONGENERATOR_BASE_URL")
183-
### replace @__REPO_ROOT_URL__ to master/commit
184-
# TODO
185-
# repo_root_url = "https://github.com/$(travis_repo_slug)/blob/$(commit)"
186-
# push!(repls, "@__REPO_ROOT_URL__" => repo_root_url)
187-
### replace @__NBVIEWER_ROOT_URL__ to dev or version directory
188182
nbviewer_root_url = "https://nbviewer.jupyter.org/urls/$(base_url)"
189183
push!(repls, "@__NBVIEWER_ROOT_URL__" => nbviewer_root_url)
190-
### replace @__BINDER_ROOT_URL__ to dev or version directory
191-
### TODO: Binder requires files to be in a git repository :(
192-
if match(r"@__BINDER_ROOT_URL__", content) !== nothing
193-
@warn("mybinder.org requires the notebook to be in a git repository, " *
194-
"which does not work with DocumentationGenerator.jl")
195-
end
196-
elseif haskey(ENV, "HAS_JOSH_K_SEAL_OF_APPROVAL") || haskey(ENV, "GITHUB_ACTION")
197-
## Travis CI / GitHub Actions
198-
### Use same logic as Documenter to figure out the deploy folder
199-
repo_slug = get(ENV, "TRAVIS_REPO_SLUG", get(ENV, "GITHUB_REPOSITORY", "REPO_SLUG"))
200-
tag = get(ENV, "TRAVIS_TAG") do
201-
github_ref = get(ENV, "GITHUB_REF", nothing)
202-
github_ref === nothing && return nothing
203-
m = match(r"^refs/tags/(.*)$", github_ref)
204-
m === nothing && return nothing
205-
return String(m.captures[1])
206-
end
207-
### use the versioned directory for links, even for the stable
208-
### and release folders since these will not change
209-
folder = (tag === nothing || isempty(tag)) ? "dev" : tag
210-
### replace @__REPO_ROOT_URL__ to master/commit
211-
repo_root_url = "https://github.com/$(repo_slug)/blob/$(commit)"
212-
push!(repls, "@__REPO_ROOT_URL__" => repo_root_url)
213-
### replace @__NBVIEWER_ROOT_URL__ to dev or version directory
214-
nbviewer_root_url = "https://nbviewer.jupyter.org/github/$(repo_slug)/blob/$(branch)/$(folder)"
215-
push!(repls, "@__NBVIEWER_ROOT_URL__" => nbviewer_root_url)
216-
### replace @__BINDER_ROOT_URL__ to dev or version directory
217-
binder_root_url = "https://mybinder.org/v2/gh/$(repo_slug)/$(branch)?filepath=$(folder)"
218-
push!(repls, "@__BINDER_ROOT_URL__" => binder_root_url)
219184
else
220-
## Warn about broken link expansions
221-
if (match(r"@__REPO_ROOT_URL__", content) !== nothing) ||
222-
(match(r"@__NBVIEWER_ROOT_URL__", content) !== nothing) ||
223-
(match(r"@__BINDER_ROOT_URL__", content) !== nothing)
224-
@warn("expansion of `@__REPO_ROOT_URL__`, `@__NBVIEWER_ROOT_URL__` and " *
225-
" `@__BINDER_ROOT_URL__` will only be correct if running from " *
226-
"DocumentationGenerator.jl, Travis CI or GitHub Actions.")
227-
end
185+
push!(repls, "@__REPO_ROOT_URL__" => get(config, "repo_root_url", "<unknown>"))
186+
push!(repls, "@__NBVIEWER_ROOT_URL__" => get(config, "nbviewer_root_url", "<unknown>"))
187+
push!(repls, "@__BINDER_ROOT_URL__" => get(config, "binder_root_url", "<unknown>"))
228188
end
229189

230190
# run some Documenter specific things
@@ -262,6 +222,53 @@ function create_configuration(inputfile; user_config, user_kwargs)
262222
cfg["codefence"] = get(user_config, "documenter", true) ?
263223
("```@example $(get(user_config, "name", cfg["name"]))" => "```") : ("```julia" => "```")
264224
cfg["execute"] = true
225+
# Guess the package (or repository) root url
226+
edit_commit = "master" # TODO: Make this configurable like Documenter?
227+
deploy_branch = "gh-pages" # TODO: Make this configurable like Documenter?
228+
if haskey(ENV, "HAS_JOSH_K_SEAL_OF_APPROVAL") # Travis CI
229+
repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "unknown-repository")
230+
deploy_folder = if get(ENV, "TRAVIS_PULL_REQUEST", nothing) == "false"
231+
get(ENV, "TRAVIS_TAG", get(user_config, "devurl", "dev"))
232+
else
233+
"previews/PR$(get(ENV, "TRAVIS_PULL_REQUEST", "##"))"
234+
end
235+
cfg["repo_root_url"] = "https://github.com/$(repo_slug)/blob/$(edit_commit)"
236+
cfg["nbviewer_root_url"] = "https://nbviewer.jupyter.org/github/$(repo_slug)/blob/$(deploy_branch)/$(deploy_folder)"
237+
cfg["binder_root_url"] = "https://mybinder.org/v2/gh/$(repo_slug)/$(deploy_branch)?filepath=$(deploy_folder)"
238+
if (dir = get(ENV, "TRAVIS_BUILD_DIR", nothing)) !== nothing
239+
cfg["repo_root_path"] = dir
240+
end
241+
elseif haskey(ENV, "GITHUB_ACTIONS")
242+
repo_slug = get(ENV, "GITHUB_REPOSITORY", "unknown-repository")
243+
deploy_folder = if get(ENV, "GITHUB_EVENT_NAME", nothing) == "push"
244+
if (m = match(r"^refs\/tags\/(.*)$", get(ENV, "GITHUB_REF", ""))) !== nothing
245+
String(m.captures[1])
246+
else
247+
get(user_config, "devurl", "dev")
248+
end
249+
elseif (m = match(r"refs\/pull\/(\d+)\/merge", get(ENV, "GITHUB_REF", ""))) !== nothing
250+
"previews/PR$(m.captures[1])"
251+
else
252+
"dev"
253+
end
254+
cfg["repo_root_url"] = "https://github.com/$(repo_slug)/blob/$(edit_commit)"
255+
cfg["nbviewer_root_url"] = "https://nbviewer.jupyter.org/github/$(repo_slug)/blob/$(deploy_branch)/$(deploy_folder)"
256+
cfg["binder_root_url"] = "https://mybinder.org/v2/gh/$(repo_slug)/$(deploy_branch)?filepath=$(deploy_folder)"
257+
if (dir = get(ENV, "GITHUB_WORKSPACE", nothing)) !== nothing
258+
cfg["repo_root_path"] = dir
259+
end
260+
elseif haskey(ENV, "GITLAB_CI")
261+
if (url = get(ENV, "CI_PROJECT_URL", nothing)) !== nothing
262+
cfg["repo_root_url"] = "$(url)/blob/$(edit_commit)"
263+
end
264+
if (url = get(ENV, "CI_PAGES_URL", nothing)) !== nothing &&
265+
(m = match(r"https://(.+)", url)) !== nothing
266+
cfg["nbviewer_root_url"] = "https://nbviewer.jupyter.org/urls/$(m[1])"
267+
end
268+
if (dir = get(ENV, "CI_PROJECT_DIR", nothing)) !== nothing
269+
cfg["repo_root_path"] = dir
270+
end
271+
end
265272

266273
# Merge default_config with user_config
267274
merge!(cfg, user_config)
@@ -285,6 +292,11 @@ See the manual section about [Configuration](@ref) for more information.
285292
| `keep_comments` | When `true`, keeps markdown lines as comments in the output script. | `false` | Only applicable for `Literate.script`. |
286293
| `codefence` | Pair containing opening and closing fence for wrapping code blocks. | `````"```julia" => "```"````` | If `documenter` is `true` the default is `````"```@example"=>"```"`````. |
287294
| `execute` | Whether to execute and capture the output. | `true` | Only applicable for `Literate.notebook`. |
295+
| `devurl` | URL for "in-development" docs. | `"dev"` | See [Documenter docs](https://juliadocs.github.io/Documenter.jl/). Unused if `repo_root_url`/`nbviewer_root_url`/`binder_root_url` are set. |
296+
| `repo_root_url` | URL to the root of the repository. | - | Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for `@__REPO_ROOT_URL__`. |
297+
| `nbviewer_root_url` | URL to the root of the repository as seen on nbviewer. | - | Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for `@__NBVIEWER_ROOT_URL__`. |
298+
| `binder_root_url` | URL to the root of the repository as seen on mybinder. | - | Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for `@__BINDER_ROOT_URL__`. |
299+
| `repo_root_path` | Filepath to the root of the repository. | - | Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing [Documenters `EditURL`](@ref Interaction-with-Documenter). |
288300
"""
289301
const DEFAULT_CONFIGURATION=nothing # Dummy const for documentation
290302

@@ -377,20 +389,8 @@ function markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
377389
# run some Documenter specific things
378390
if config["documenter"]::Bool
379391
# change the Edit on GitHub link
380-
repo = get(ENV, "TRAVIS_REPO_SLUG", get(ENV, "GITHUB_REPOSITORY", nothing))
381-
if repo === nothing
382-
path = ""
383-
else
384-
pkg = String(first(split(last(split(repo, '/')), '.')))
385-
pkgsrc = Base.find_package(pkg)
386-
if pkgsrc === nothing
387-
path = ""
388-
else
389-
repo_root = first(split(pkgsrc, joinpath("src", pkg * ".jl")))
390-
path = relpath(inputfile, repo_root)
391-
path = replace(path, "\\" => "/")
392-
end
393-
end
392+
path = relpath(inputfile, get(config, "repo_root_path", pwd())::String)
393+
path = replace(path, "\\" => "/")
394394
content = """
395395
# ```@meta
396396
# EditURL = "@__REPO_ROOT_URL__/$(path)"

0 commit comments

Comments
 (0)