diff --git a/docs/literate.jl b/docs/literate.jl deleted file mode 100644 index b4547644..00000000 --- a/docs/literate.jl +++ /dev/null @@ -1,92 +0,0 @@ -# Retrieve name of example and output directory -if length(ARGS) != 2 - error("please specify the name of the example and the output directory") -end -const EXAMPLE = ARGS[1] -const OUTDIR = ARGS[2] - -# Activate environment -# Note that each example's Project.toml must include Literate as a dependency -using Pkg: Pkg - -using InteractiveUtils -const EXAMPLEPATH = joinpath(@__DIR__, "..", "examples", EXAMPLE) -const PKGDIR = joinpath(@__DIR__, "..") -Pkg.activate(EXAMPLEPATH) -Pkg.instantiate() -pkg_status = sprint() do io - Pkg.status(; io=io) -end -Pkg.develop(Pkg.PackageSpec(path=PKGDIR)) - -using Literate: Literate - -const MANIFEST_OUT = joinpath(EXAMPLE, "Manifest.toml") -mkpath(joinpath(OUTDIR, EXAMPLE)) -cp(joinpath(EXAMPLEPATH, "Manifest.toml"), joinpath(OUTDIR, MANIFEST_OUT); force=true) - -using Markdown: htmlesc - -function preprocess(content) - # Add link to nbviewer below the first heading of level 1 - sub = SubstitutionString( - """ -#md # ```@meta -#md # EditURL = "@__REPO_ROOT_URL__/examples/@__NAME__/script.jl" -#md # ``` -#md # -\\0 -# -#md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/examples/@__NAME__.ipynb) -#md # -# *You are seeing the -#md # HTML output generated by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) and -#nb # notebook output generated by -# [Literate.jl](https://github.com/fredrikekre/Literate.jl) from the -# [Julia source file](@__REPO_ROOT_URL__/examples/@__NAME__/script.jl). -#md # The corresponding notebook can be viewed in [nbviewer](@__NBVIEWER_ROOT_URL__/examples/@__NAME__.ipynb).* -#nb # The rendered HTML can be viewed [in the docs](https://juliagaussianprocesses.github.io/ApproximateGPs.jl/dev/examples/@__NAME__/).* -# -#md # --- -# - """, - ) - content = replace(content, r"^# # [^\n]*"m => sub; count=1) - - # remove VSCode `##` block delimiter lines - content = replace(content, r"^##$."ms => "") - - """ The regex adds "# " at the beginning of each line; chomp removes trailing newlines """ - literate_format(s) = chomp(replace(s, r"^"m => "# ")) - - #
seems to be buggy in the notebook, so is avoided for now - info_footer = """ - #md # ```@raw html - #
- #
Package and system information
- #
- # Package information (click to expand) - #
-    $(literate_format(htmlesc(pkg_status)))
-    # 
- # To reproduce this notebook's package environment, you can - #nb # - #md # - # download the full Manifest.toml. - #
- #
- # System information (click to expand) - #
-    $(literate_format(htmlesc(sprint(InteractiveUtils.versioninfo))))
-    # 
- #
- #md # ``` - """ - - return content * info_footer -end - -# Convert to markdown and notebook -const SCRIPTJL = joinpath(EXAMPLEPATH, "script.jl") -Literate.markdown(SCRIPTJL, OUTDIR; name=EXAMPLE, execute=true, preprocess=preprocess) -Literate.notebook(SCRIPTJL, OUTDIR; name=EXAMPLE, execute=true, preprocess=preprocess) diff --git a/docs/make.jl b/docs/make.jl index 6a22e1dd..08957400 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,46 +1,15 @@ ### Process examples -# Always rerun examples -const EXAMPLES_OUT = joinpath(@__DIR__, "src", "examples") -ispath(EXAMPLES_OUT) && rm(EXAMPLES_OUT; recursive=true) -mkpath(EXAMPLES_OUT) - -# Install and precompile all packages -# Workaround for https://github.com/JuliaLang/Pkg.jl/issues/2219 -examples = filter!(isdir, readdir(joinpath(@__DIR__, "..", "examples"); join=true)) -let script = "using Pkg; Pkg.activate(ARGS[1]); Pkg.instantiate()" - for example in examples - if !success(`$(Base.julia_cmd()) -e $script $example`) - error( - "project environment of example ", - basename(example), - " could not be instantiated", - ) - end - end -end -# Run examples asynchronously -processes = let literatejl = joinpath(@__DIR__, "literate.jl") - map(examples) do example - return run( - pipeline( - `$(Base.julia_cmd()) $literatejl $(basename(example)) $EXAMPLES_OUT`; - stdin=devnull, - stdout=devnull, - stderr=stderr, - ); - wait=false, - )::Base.Process - end -end - -# Check that all examples were run successfully -isempty(processes) || success(processes) || error("some examples were not run successfully") +using Pkg +Pkg.add(Pkg.PackageSpec(; url="https://github.com/JuliaGaussianProcesses/JuliaGPsDocs.jl")) # While the package is unregistered, it's a workaround ### Build documentation using Documenter +using JuliaGPsDocs using ApproximateGPs +JuliaGPsDocs.generate_examples(ApproximateGPs) + # Doctest setup DocMeta.setdocmeta!( ApproximateGPs, @@ -58,11 +27,14 @@ makedocs(; pages=[ "Home" => "index.md", "userguide.md", - "API" => ["api/index.md", "api/sparsevariational.md", "api/laplace.md"], - "Examples" => - map(filter!(filename -> endswith(filename, ".md"), readdir(EXAMPLES_OUT))) do x - return joinpath("examples", x) - end, + "API" => joinpath.(Ref("api"), ["index.md", "sparsevariational.md", "laplace.md"]), + "Examples" => map( + basename.( + filter!(isdir, readdir(joinpath(@__DIR__, "src", "examples"); join=true)), + ), + ) do x + joinpath("examples", x, "index.md") + end, ], strict=true, checkdocs=:exports,