From 69d21c3a3cfbf3ed6de178ddd00d0705e8c206a4 Mon Sep 17 00:00:00 2001 From: Jeff Fessler Date: Mon, 31 Oct 2022 21:02:31 -0400 Subject: [PATCH 1/5] Tweak Documentation.yml --- .github/workflows/Documentation.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml index d83faef..4f0ce9f 100644 --- a/.github/workflows/Documentation.yml +++ b/.github/workflows/Documentation.yml @@ -3,10 +3,10 @@ name: Documentation on: pull_request: paths-ignore: - - 'README.md' + - 'README.md' push: paths-ignore: - - 'README.md' + - 'README.md' branches: - 'master' - 'release-' From 5bf4927c5ef6b888f5e86531e6e3eef100119fe8 Mon Sep 17 00:00:00 2001 From: Jeff Fessler Date: Mon, 31 Oct 2022 21:07:39 -0400 Subject: [PATCH 2/5] Stop make.jl from making previews --- docs/make.jl | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 7602f55..334718e 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -7,13 +7,13 @@ using Literate # https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@example-block ENV["GKSwstype"] = "100" +ENV["GKS_ENCODING"] = "utf-8" -# generate tutorials and how-to guides using Literate +# generate examples using Literate lit = joinpath(@__DIR__, "lit") src = joinpath(@__DIR__, "src") notebooks = joinpath(src, "notebooks") -ENV["GKS_ENCODING"] = "utf-8" DocMeta.setdocmeta!(SpecialMatrices, :DocTestSetup, :(using SpecialMatrices); recursive=true) @@ -27,6 +27,7 @@ for (root, _, files) in walkdir(lit), file in files nb && Literate.notebook(ipath, notebooks, execute = execute) end + # Documentation structure ismd(f) = splitext(f)[2] == ".md" pages(folder) = @@ -59,9 +60,7 @@ if isci devurl = "dev", versions = ["stable" => "v^", "dev" => "dev"], forcepush = true, - push_preview = true, +# push_preview = true, # see https://JuliaMatrices.github.io/SpecialMatrices.jl/previews/PR## ) -else - @warn "may need to: rm -r src/examples" end From 7af1d3880b938376200d8f98a95a693531b87b24 Mon Sep 17 00:00:00 2001 From: Jeff Fessler Date: Mon, 31 Oct 2022 22:07:24 -0400 Subject: [PATCH 3/5] Fix url --- docs/lit/examples/1-overview.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/lit/examples/1-overview.jl b/docs/lit/examples/1-overview.jl index 2e965e4..4dbf15d 100644 --- a/docs/lit/examples/1-overview.jl +++ b/docs/lit/examples/1-overview.jl @@ -3,7 +3,7 @@ #--------------------------------------------------------- # This page illustrates the Julia package -# [`SpecialMatrices`](https://github.com/JuliaMatrices/SpecialMatrices.jl). +# [`SpecialMatrices`](https://github.com/JuliaLinearAlgebra/SpecialMatrices.jl). # ### Setup From fe17f9db81a912e2bba02e554e4ebb6cdee57dea Mon Sep 17 00:00:00 2001 From: Jeff Fessler Date: Mon, 31 Oct 2022 22:08:04 -0400 Subject: [PATCH 4/5] Unify make.jl --- docs/make.jl | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 334718e..cd6ef7b 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,10 +1,10 @@ -using SpecialMatrices +execute = isempty(ARGS) || ARGS[1] == "run" + +org, reps = :JuliaLinearAlgebra, :SpecialMatrices +eval(:(using $reps)) using Documenter using Literate -# based on: -# https://github.com/jw3126/UnitfulRecipes.jl/blob/master/docs/make.jl - # https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@example-block ENV["GKSwstype"] = "100" ENV["GKS_ENCODING"] = "utf-8" @@ -12,39 +12,48 @@ ENV["GKS_ENCODING"] = "utf-8" # generate examples using Literate lit = joinpath(@__DIR__, "lit") src = joinpath(@__DIR__, "src") -notebooks = joinpath(src, "notebooks") +gen = joinpath(@__DIR__, "src/generated") + +base = "$org/$reps.jl" +repo_root_url = + "https://github.com/$base/blob/main/docs/lit/examples" +nbviewer_root_url = + "https://nbviewer.org/github/$base/tree/gh-pages/dev/generated/examples" +binder_root_url = + "https://mybinder.org/v2/gh/$base/gh-pages?filepath=dev/generated/examples" -DocMeta.setdocmeta!(SpecialMatrices, :DocTestSetup, :(using SpecialMatrices); recursive=true) +repo = eval(:($reps)) +DocMeta.setdocmeta!(repo, :DocTestSetup, :(using $reps); recursive=true) -execute = true # Set to true for executing notebooks and documenter! -nb = false # Set to true to generate the notebooks for (root, _, files) in walkdir(lit), file in files - splitext(file)[2] == ".jl" || continue + splitext(file)[2] == ".jl" || continue # process .jl files only ipath = joinpath(root, file) - opath = splitdir(replace(ipath, lit=>src))[1] - Literate.markdown(ipath, opath, documenter = execute) - nb && Literate.notebook(ipath, notebooks, execute = execute) + opath = splitdir(replace(ipath, lit => gen))[1] + Literate.markdown(ipath, opath; documenter = execute, # run examples + repo_root_url, nbviewer_root_url, binder_root_url) + Literate.notebook(ipath, opath; execute = false, # no-run notebooks + repo_root_url, nbviewer_root_url, binder_root_url) end # Documentation structure ismd(f) = splitext(f)[2] == ".md" pages(folder) = - [joinpath(folder, f) for f in readdir(joinpath(src, folder)) if ismd(f)] + [joinpath("generated/", folder, f) for f in readdir(joinpath(gen, folder)) if ismd(f)] isci = get(ENV, "CI", nothing) == "true" format = Documenter.HTML(; prettyurls = isci, edit_link = "master", - canonical = "https://JuliaMatrices.github.io/SpecialMatrices.jl/stable/", + canonical = "https://$org.github.io/$repo.jl/stable/", # assets = String[], ) makedocs(; - modules = [SpecialMatrices], - sitename = "SpecialMatrices.jl", + modules = [repo], + sitename = "$repo.jl", format, pages = [ "Home" => "index.md", @@ -55,12 +64,12 @@ makedocs(; if isci deploydocs(; - repo = "github.com/JuliaMatrices/SpecialMatrices.jl", + repo = "github.com/$base", devbranch = "master", devurl = "dev", versions = ["stable" => "v^", "dev" => "dev"], forcepush = true, # push_preview = true, - # see https://JuliaMatrices.github.io/SpecialMatrices.jl/previews/PR## + # see https://$org.github.io/$repo.jl/previews/PR## ) end From f0f858be34cf55ed80e51d453f430900a58150d7 Mon Sep 17 00:00:00 2001 From: Jeff Fessler Date: Mon, 31 Oct 2022 22:08:22 -0400 Subject: [PATCH 5/5] Ignore Documenter generated files --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 99d5d15..27686f9 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,7 @@ deps/src/ # Build artifacts for creating documentation generated by the Documenter package docs/build/ docs/site/ +docs/src/generated/ # File generated by Pkg, the package manager, based on a corresponding Project.toml # It records a fixed state of all packages used by the project. As such, it should not be