diff --git a/.gitignore b/.gitignore index 58142391..97daecdc 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,8 @@ /test/Manifest.toml .vscode /docs/src/examples/generated/ +# ignore .md generated from notebooks +/docs/src/pluto-notebooks/*.md /sandbox/* /talks/* diff --git a/docs/make.jl b/docs/make.jl index 81e1a8c5..3e4b5620 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -2,8 +2,8 @@ using Inti using Documenter using DocumenterCitations using DocumenterInterLinks -using ExampleJuggler, Literate, PlutoSliderServer -using Pluto, JuliaFormatter +using Pluto +using JuliaFormatter # packages needed for extensions using Gmsh using HMatrices @@ -12,8 +12,6 @@ using GLMakie using FMM2D using FMM3D -cleanexamples() - # from https://github.com/fonsp/Pluto.jl/pull/2471 function generate_plaintext( notebook, @@ -56,25 +54,22 @@ function generate_plaintext( return join(cell_strings, "\n\n") end -function generate_md( - input; - output = replace(replace(input, r"..$" => "md"), "pluto-examples" => "module_examples"), -) +notebook_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "pluto-notebooks") + +function generate_md(input; output = replace(input, ".jl" => ".md")) notebook = Pluto.load_notebook(input) - header = _ -> "" fname = basename(input) + function header(_) + return "[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)]($fname)" + end function codewrapper(cell, _) # 1. Strips begin/end block # 2. Reformats code using JuliaFormatter # 3. Wraps all code in same ```@example``` block for documenter code = strip(cell.code) if startswith(code, "begin") && endswith(code, "end") - code = strip(code[6:end-4]) # Remove "begin" and "end" and strip spaces - # reformat code using JuliaFormatter - code = format_text(String(code)) - elseif startswith(code, "let") && endswith(code, "end") - code = strip(code[4:end-4]) # Remove "let" and "end" and strip spaces - # reformat code using JuliaFormatter + # Remove "begin" and "end" and reformat block + code = strip(code[6:end-4]) code = format_text(String(code)) end return if cell.code_folded @@ -102,43 +97,9 @@ draft = false const ON_CI = get(ENV, "CI", "false") == "true" const GIT_HEAD = chomp(read(`git rev-parse HEAD`, String)) -const SETUP = """ -#nb import Pkg -#nb Pkg.activate(temp=true) -#nb Pkg.add(url="https://github.com/IntegralEquations/Inti.jl", rev="$GIT_HEAD") -#nb foreach(Pkg.add, DEPENDENCIES) -""" ON_CI && (draft = false) # always full build on CI -function insert_setup(content) - ON_CI || return content - return replace(content, "#nb ## __NOTEBOOK_SETUP__" => SETUP) -end - -## TO REMOVE if we decide to use Pluto Notebooks to generate documentation -# Generate examples using Literate -# const examples_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "examples") -const notebook_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "pluto-examples") -# const generated_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "examples", "generated") -# const examples = ["toy_example.jl", "helmholtz_scattering.jl"] -# for t in examples -# println("\n*** Generating $t example") -# @time begin -# src = joinpath(examples_dir, t) -# Literate.markdown(src, generated_dir; mdstrings = true) -# # if draft, skip creation of notebooks -# Literate.notebook( -# src, -# generated_dir; -# mdstrings = true, -# preprocess = insert_setup, -# # execute = ON_CI, -# execute = false, -# ) -# end -# end - println("\n*** Generating documentation") DocMeta.setdocmeta!(Inti, :DocTestSetup, :(using Inti); recursive = true) @@ -154,26 +115,20 @@ end size_threshold_ignore = [] notebooks = [ "Toy example" => "toy_example.jl", - "Helmholtz scattering" => "helmholtz_scattering.jl", - "Poisson problem" => "poisson.jl", + # "Helmholtz scattering" => "helmholtz_scattering.jl", + # "Poisson problem" => "poisson.jl", ] -mkdir(joinpath(Inti.PROJECT_ROOT, "docs", "src", "module_examples")) - notebook_examples = Pair{String,String}[] for notebook in notebooks name, file = notebook file_in = joinpath(notebook_dir, file) file_out = generate_md(file_in) - push!( - notebook_examples, - name => joinpath("module_examples", replace(file, ".jl" => ".md")), - ) + push!(notebook_examples, name => "pluto-notebooks/$(basename(file_out))") end -size_threshold_ignore = last.(notebook_examples) -# Generate HTML versions of the notebooks using PlutoSliderServer.jl -# notebook_examples_html = @docplutonotebooks(notebook_dir, notebooks, iframe = true) +# ignore size threshold for notebooks +size_threshold_ignore = last.(notebook_examples) makedocs(; modules = modules, @@ -199,19 +154,11 @@ makedocs(; "tutorials/correction_methods.md", "tutorials/solvers.md", ], - # "Examples" => [ - # "examples/generated/toy_example.md", - # "examples/generated/helmholtz_scattering.md", - # "examples/poisson.md", - # # "examples/generated/lippmann_schwinger.md", - # # "examples/generated/poisson.md", - # # "examples/generated/stokes_drag.md", - # ], "Notebooks" => notebook_examples, "References" => "references.md", "Docstrings" => "docstrings.md", ], - warnonly = Documenter.except(:linkcheck_remotes), # ON_CI ? false : Documenter.except(:linkcheck_remotes), + warnonly = ON_CI ? false : Documenter.except(:linkcheck_remotes), # warnonly = true, pagesonly = true, checkdocs = :none, @@ -220,8 +167,6 @@ makedocs(; plugins = [bib, links], ) -cleanexamples() - deploydocs(; repo = "github.com/IntegralEquations/Inti.jl", devbranch = "main", diff --git a/docs/src/pluto-examples/toy_example.md b/docs/src/pluto-examples/toy_example.md deleted file mode 100644 index 2ddca8fc..00000000 --- a/docs/src/pluto-examples/toy_example.md +++ /dev/null @@ -1,19 +0,0 @@ - - -```julia -begin - import Pkg as _Pkg - haskey(ENV, "PLUTO_PROJECT") && _Pkg.activate(ENV["PLUTO_PROJECT"]) - using PlutoUI: with_terminal -end ; -``` - -# Toy example - -[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)](../../build/pluto_examples/toy_example.jl) $\hspace{0.2cm}$ [![nbviewer](https://img.shields.io/badge/show-nbviewer-blue.svg)](../../build/pluto_examples/toy_example.html) - -All examples in Inti.jl are autogenerated by executing the `make.jl` script in the `docs` folder. The workflow uses [PlutoStaticHTML.jl](https://plutostatichtml.huijzer.xyz/stable/) and [PlutoSliderServer.jl](https://github.com/JuliaPluto/PlutoSliderServer.jl) via the intermediate of [ExampleJuggler.jl](https://github.com/j-fu/ExampleJuggler.jl) to generate (i) markdown files passed to Documenter.jl, and (ii) pluto notebook files downloadable from the example's page. - -```julia -using Inti -``` \ No newline at end of file diff --git a/docs/src/pluto-examples/helmholtz_scattering.jl b/docs/src/pluto-notebooks/helmholtz_scattering.jl similarity index 100% rename from docs/src/pluto-examples/helmholtz_scattering.jl rename to docs/src/pluto-notebooks/helmholtz_scattering.jl diff --git a/docs/src/pluto-examples/poisson.jl b/docs/src/pluto-notebooks/poisson.jl similarity index 100% rename from docs/src/pluto-examples/poisson.jl rename to docs/src/pluto-notebooks/poisson.jl diff --git a/docs/src/pluto-examples/toy_example.jl b/docs/src/pluto-notebooks/toy_example.jl similarity index 94% rename from docs/src/pluto-examples/toy_example.jl rename to docs/src/pluto-notebooks/toy_example.jl index 81fc763a..e32ba489 100644 --- a/docs/src/pluto-examples/toy_example.jl +++ b/docs/src/pluto-notebooks/toy_example.jl @@ -1,5 +1,5 @@ ### A Pluto.jl notebook ### -# v0.19.46 +# v0.19.47 using Markdown using InteractiveUtils @@ -9,20 +9,21 @@ using Inti # ╔═╡ 3f5a1750-7cd7-11ef-2223-4f3db029916b begin - import Pkg as _Pkg - haskey(ENV, "PLUTO_PROJECT") && _Pkg.activate(ENV["PLUTO_PROJECT"]) -end ; + import Pkg as _Pkg + haskey(ENV, "PLUTO_PROJECT") && _Pkg.activate(ENV["PLUTO_PROJECT"]) +end; # ╔═╡ 854743f0-8556-4495-ba16-52514c85922a md""" # Toy example - -[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)](../../pluto_examples/toy_example.jl)$\hspace{5pt}$[![nbviewer](https://img.shields.io/badge/show-nbviewer-blue.svg)](../../pluto_examples/toy_example.html) """ # ╔═╡ 09c0bfc0-1c65-4fad-b486-b6a61ca580e8 md""" -All examples in Inti.jl are autogenerated by executing the `make.jl` script in the `docs` folder. The workflow uses [Pluto.jl](https://plutojl.org), [JuliaFormatter](https://domluna.github.io/JuliaFormatter.jl/stable/), and [PlutoSliderServer.jl](https://github.com/JuliaPluto/PlutoSliderServer.jl) (via the intermediate of [ExampleJuggler.jl](https://github.com/j-fu/ExampleJuggler.jl)) to generate (i) markdown files passed to Documenter.jl, and (ii) pluto notebook files downloadable from the example's page. +All examples in Inti.jl are autogenerated by executing the `make.jl` script in +the `docs` folder. The workflow uses [Pluto.jl](https://plutojl.org) to generate +(i) markdown files passed to Documenter.jl, and (ii) pluto notebook files +downloadable from the example's page. """ # ╔═╡ 00000000-0000-0000-0000-000000000001