diff --git a/docs/inc/reproduce.jl b/docs/inc/reproduce.jl new file mode 100644 index 0000000..8b64f28 --- /dev/null +++ b/docs/inc/reproduce.jl @@ -0,0 +1,9 @@ + +# ### Reproducibility + +# This page was generated with the following version of Julia: +using InteractiveUtils: versioninfo +io = IOBuffer(); versioninfo(io); split(String(take!(io)), '\n') + +# And with the following package versions +import Pkg; Pkg.status() diff --git a/docs/inc/urls.jl b/docs/inc/urls.jl new file mode 100644 index 0000000..0aab175 --- /dev/null +++ b/docs/inc/urls.jl @@ -0,0 +1,14 @@ + +#= +This page comes from a single Julia file: +[`@__NAME__.jl`](xxxrepo/@__NAME__.jl). + +You can access the source code +for such Julia documentation +using the 'Edit on GitHub' link in the top right. +You can view the corresponding notebook in +[nbviewer](https://nbviewer.org/) here: +[`@__NAME__.ipynb`](xxxnb/@__NAME__.ipynb), +or open it in [binder](https://mybinder.org/) here: +[`@__NAME__.ipynb`](xxxbinder/@__NAME__.ipynb). +=# diff --git a/docs/lit/examples/1-overview.jl b/docs/lit/examples/1-overview.jl index 41f5922..e911f63 100644 --- a/docs/lit/examples/1-overview.jl +++ b/docs/lit/examples/1-overview.jl @@ -3,22 +3,11 @@ This page gives an overview of the Julia package [`SPECTrecon`](https://github.com/JuliaImageRecon/SPECTrecon.jl). - -This page was generated from a single Julia file: -[1-overview.jl](@__REPO_ROOT_URL__/1-overview.jl). =# -#md # In any such Julia documentation, -#md # you can access the source code -#md # using the "Edit on GitHub" link in the top right. - -#md # The corresponding notebook can be viewed in -#md # [nbviewer](https://nbviewer.org/) here: -#md # [`1-overview.ipynb`](@__NBVIEWER_ROOT_URL__/1-overview.ipynb), -#md # and opened in [binder](https://mybinder.org/) here: -#md # [`1-overview.ipynb`](@__BINDER_ROOT_URL__/1-overview.ipynb). +#srcURL -# ## Setup +# ### Setup # Packages needed here. @@ -247,13 +236,4 @@ end gif(anim, "views.gif", fps = 8) -# ## Reproducibility - -# This page was generated with the following version of Julia: - -io = IOBuffer(); versioninfo(io); split(String(take!(io)), '\n') - - -# And with the following package versions - -import Pkg; Pkg.status() +include("../../../inc/reproduce.jl") diff --git a/docs/lit/examples/2-rotate.jl b/docs/lit/examples/2-rotate.jl index ac2c602..95237af 100644 --- a/docs/lit/examples/2-rotate.jl +++ b/docs/lit/examples/2-rotate.jl @@ -3,20 +3,9 @@ This page explains the image rotation portion of the Julia package [`SPECTrecon.jl`](https://github.com/JuliaImageRecon/SPECTrecon.jl). - -This page was generated from a single Julia file: -[2-rotate.jl](@__REPO_ROOT_URL__/2-rotate.jl). =# -#md # In any such Julia documentation, -#md # you can access the source code -#md # using the "Edit on GitHub" link in the top right. - -#md # The corresponding notebook can be viewed in -#md # [nbviewer](https://nbviewer.org/) here: -#md # [`2-rotate.ipynb`](@__NBVIEWER_ROOT_URL__/2-rotate.ipynb), -#md # and opened in [binder](https://mybinder.org/) here: -#md # [`2-rotate.ipynb`](@__BINDER_ROOT_URL__/2-rotate.ipynb). +#srcURL # ## Setup diff --git a/docs/lit/examples/3-psf.jl b/docs/lit/examples/3-psf.jl index c84b92f..50e528c 100644 --- a/docs/lit/examples/3-psf.jl +++ b/docs/lit/examples/3-psf.jl @@ -3,20 +3,9 @@ This page explains the PSF portion of the Julia package [`SPECTrecon.jl`](https://github.com/JuliaImageRecon/SPECTrecon.jl). - -This page was generated from a single Julia file: -[3-psf.jl](@__REPO_ROOT_URL__/3-psf.jl). =# -#md # In any such Julia documentation, -#md # you can access the source code -#md # using the "Edit on GitHub" link in the top right. - -#md # The corresponding notebook can be viewed in -#md # [nbviewer](https://nbviewer.org/) here: -#md # [`3-psf.ipynb`](@__NBVIEWER_ROOT_URL__/3-psf.ipynb), -#md # and opened in [binder](https://mybinder.org/) here: -#md # [`3-psf.ipynb`](@__BINDER_ROOT_URL__/3-psf.ipynb). +#srcURL # ## Setup diff --git a/docs/lit/examples/4-mlem.jl b/docs/lit/examples/4-mlem.jl index 6eca972..96dd59b 100644 --- a/docs/lit/examples/4-mlem.jl +++ b/docs/lit/examples/4-mlem.jl @@ -3,20 +3,9 @@ This page illustrates ML-EM reconstruction with the Julia package [`SPECTrecon`](https://github.com/JuliaImageRecon/SPECTrecon.jl). - -This page was generated from a single Julia file: -[4-mlem.jl](@__REPO_ROOT_URL__/4-mlem.jl). =# -#md # In any such Julia documentation, -#md # you can access the source code -#md # using the "Edit on GitHub" link in the top right. - -#md # The corresponding notebook can be viewed in -#md # [nbviewer](https://nbviewer.org/) here: -#md # [`4-mlem.ipynb`](@__NBVIEWER_ROOT_URL__/4-mlem.ipynb), -#md # and opened in [binder](https://mybinder.org/) here: -#md # [`4-mlem.ipynb`](@__BINDER_ROOT_URL__/4-mlem.ipynb). +#srcURL # ## Setup diff --git a/docs/lit/examples/5-2d.jl b/docs/lit/examples/5-2d.jl index 49de5a0..81662d4 100644 --- a/docs/lit/examples/5-2d.jl +++ b/docs/lit/examples/5-2d.jl @@ -4,21 +4,9 @@ This page describes how to perform 2D SPECT forward and back-projection using the Julia package [`SPECTrecon`](https://github.com/JuliaImageRecon/SPECTrecon.jl). - -This page was generated from a single Julia file: -[5-2d.jl](@__REPO_ROOT_URL__/5-2d.jl). =# -#md # In any such Julia documentation, -#md # you can access the source code -#md # using the "Edit on GitHub" link in the top right. - -#md # The corresponding notebook can be viewed in -#md # [nbviewer](https://nbviewer.org/) here: -#md # [`5-2d.ipynb`](@__NBVIEWER_ROOT_URL__/5-2d.ipynb), -#md # and opened in [binder](https://mybinder.org/) here: -#md # [`5-2d.ipynb`](@__BINDER_ROOT_URL__/5-2d.ipynb). - +#srcURL # ### Setup diff --git a/docs/lit/examples/6-dl.jl b/docs/lit/examples/6-dl.jl index c60daa0..60c1888 100644 --- a/docs/lit/examples/6-dl.jl +++ b/docs/lit/examples/6-dl.jl @@ -4,20 +4,9 @@ This page describes how to end-to-end train unrolled deep learning algorithms using the Julia package [`SPECTrecon`](https://github.com/JuliaImageRecon/SPECTrecon.jl). - -This page was generated from a single Julia file: -[6-dl.jl](@__REPO_ROOT_URL__/6-dl.jl). =# -#md # In any such Julia documentation, -#md # you can access the source code -#md # using the "Edit on GitHub" link in the top right. - -#md # The corresponding notebook can be viewed in -#md # [nbviewer](https://nbviewer.org/) here: -#md # [`6-dl.ipynb`](@__NBVIEWER_ROOT_URL__/6-dl.ipynb), -#md # and opened in [binder](https://mybinder.org/) here: -#md # [`6-dl.ipynb`](@__BINDER_ROOT_URL__/6-dl.ipynb). +#srcURL # ### Setup @@ -295,13 +284,4 @@ see [https://doi.org/10.1109/EMBC46164.2021.9630985](https://doi.org/10.1109/EMB =# -# ### Reproducibility - -# This page was generated with the following version of Julia: - -io = IOBuffer(); versioninfo(io); split(String(take!(io)), '\n') - - -# And with the following package versions - -import Pkg; Pkg.status() +include("../../../inc/reproduce.jl") diff --git a/docs/lit/examples/7-osem.jl b/docs/lit/examples/7-osem.jl index 4dba864..e523287 100644 --- a/docs/lit/examples/7-osem.jl +++ b/docs/lit/examples/7-osem.jl @@ -5,20 +5,9 @@ This page illustrates Ordered-subset expectation-maximization (OS-EM) image reconstruction with the Julia package [`SPECTrecon`](https://github.com/JuliaImageRecon/SPECTrecon.jl). - -This page was generated from a single Julia file: -[7-osem.jl](@__REPO_ROOT_URL__/7-osem.jl). =# -#md # In any such Julia documentation, -#md # you can access the source code -#md # using the "Edit on GitHub" link in the top right. - -#md # The corresponding notebook can be viewed in -#md # [nbviewer](https://nbviewer.org/) here: -#md # [`7-osem.ipynb`](@__NBVIEWER_ROOT_URL__/7-osem.ipynb), -#md # and opened in [binder](https://mybinder.org/) here: -#md # [`7-osem.ipynb`](@__BINDER_ROOT_URL__/7-osem.ipynb). +#srcURL # ### Setup diff --git a/docs/make.jl b/docs/make.jl index 0934b3c..d5e0181 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -15,12 +15,11 @@ src = joinpath(@__DIR__, "src") gen = joinpath(@__DIR__, "src/generated") base = "$org/$reps.jl" -repo_root_url = - "https://github.com/$base/blob/main/docs/lit/examples" +repo_root_url = "https://github.com/$base/blob/main" nbviewer_root_url = - "https://nbviewer.org/github/$base/tree/gh-pages/dev/generated/examples" + "https://nbviewer.org/github/$base/tree/gh-pages/dev/generated" binder_root_url = - "https://mybinder.org/v2/gh/$base/gh-pages?filepath=dev/generated/examples" + "https://mybinder.org/v2/gh/$base/gh-pages?filepath=dev/generated" repo = eval(:($reps)) @@ -28,14 +27,41 @@ DocMeta.setdocmeta!(repo, :DocTestSetup, :(using $reps); recursive=true) #ENV["JULIA_DEBUG"] = "Literate" +# preprocessing +inc1 = "include(\"../../../inc/reproduce.jl\")" + +function prep_markdown(str, root, file) + inc_read(file) = read(joinpath("docs/inc", file), String) + repro = inc_read("reproduce.jl") + str = replace(str, inc1 => repro) + urls = inc_read("urls.jl") + file = joinpath(splitpath(root)[end], splitext(file)[1]) + tmp = splitpath(root)[end-2:end] # docs lit examples + urls = replace(urls, + "xxxrepo" => joinpath(repo_root_url, tmp...), + "xxxnb" => joinpath(nbviewer_root_url, tmp[end]), + "xxxbinder" => joinpath(binder_root_url, tmp[end]), + ) + str = replace(str, "#srcURL" => urls) +end + +function prep_notebook(str) + str = replace(str, inc1 => "", "#srcURL" => "") +end + for (root, _, files) in walkdir(lit), file in files splitext(file)[2] == ".jl" || continue # process .jl files only ipath = joinpath(root, file) 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) + Literate.markdown(ipath, opath; + repo_root_url, + preprocess = str -> prep_markdown(str, root, file), + documenter = execute, # run examples + ) + Literate.notebook(ipath, opath; + preprocess = prep_notebook, + execute = false, # no-run notebooks + ) end @@ -73,7 +99,7 @@ if isci devurl = "dev", versions = ["stable" => "v^", "dev" => "dev"], forcepush = true, -# push_preview = true, + push_preview = true, # see https://$org.github.io/$repo.jl/previews/PR## ) end