From 85fc1b5417947b05bdadd806b9656ee0fe858510 Mon Sep 17 00:00:00 2001 From: Mirek Kratochvil Date: Mon, 6 Jun 2022 11:29:01 +0200 Subject: [PATCH] more reorganization --- docs/make.jl | 50 ++++++++++++++-------------- docs/src/examples.md | 7 ++++ docs/src/functions/analysis.md | 6 ++-- docs/src/functions/base.md | 2 +- docs/src/functions/io.md | 4 +-- docs/src/functions/reconstruction.md | 4 +-- docs/src/functions/types.md | 6 ++-- docs/src/functions/utils.md | 6 ++-- docs/src/index.md.template | 9 ++--- 9 files changed, 51 insertions(+), 43 deletions(-) create mode 100644 docs/src/examples.md diff --git a/docs/make.jl b/docs/make.jl index e8a1e30af..1c8eee003 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -9,22 +9,23 @@ pages_branch = "gh-pages" # This must match the repo slug on github! github_repo_slug = ENV["CI_PROJECT_NAMESPACE"] * "/" * ENV["CI_PROJECT_NAME"] -# generate notebooks -notebooks_path = joinpath(@__DIR__, "src", "notebooks") -notebooks_basenames = filter(x -> endswith(x, ".jl"), readdir(notebooks_path)) -@info "base names:" notebooks_basenames -notebooks = joinpath.(notebooks_path, notebooks_basenames) -notebooks_outdir = joinpath(@__DIR__, "src", "notebooks") - -for notebook in notebooks +# generate examples +examples_path = joinpath(@__DIR__, "src", "examples") +examples_basenames = filter(x -> endswith(x, ".jl"), readdir(examples_path)) +@info "base names:" examples_basenames +examples = joinpath.(examples_path, examples_basenames) +examples_outdir = joinpath(@__DIR__, "src", "examples") + +for example in examples + #TODO improve how the nbviewer and binder links are inserted. Direct link to ipynb would be cool Literate.markdown( - notebook, - notebooks_outdir; + example, + examples_outdir; repo_root_url = "https://github.com/$github_repo_slug/blob/master", nbviewer_root_url = "https://nbviewer.jupyter.org/github/$github_repo_slug/blob/gh-pages/$dev_docs_folder", binder_root_url = "https://mybinder.org/v2/gh/$github_repo_slug/$pages_branch?filepath=$dev_docs_folder", ) - Literate.notebook(notebook, notebooks_outdir) + Literate.notebook(example, exampless_outdir) end # extract shared documentation parts from README.md @@ -86,12 +87,10 @@ makedocs( "Home" => "index.md", "Quick start" => "quickstart.md", "User guide" => [ - "Quickstart tutorials" => - vcat("All tutorials" => "tutorials.md", find_mds("tutorials")), - "Advanced tutorials" => - vcat("All advanced tutorials" => "advanced.md", find_mds("advanced")), "Examples and notebooks" => - vcat("All notebooks" => "notebooks.md", find_mds("notebooks")), + vcat("All examples" => "examples.md", find_mds("examples")), + "Core concepts" => + vcat("All tutorials" => "tutorials.md", find_mds("tutorials")), ], "Function reference" => vcat("Contents" => "functions.md", find_mds("functions")), "How to contribute" => "howToContribute.md", @@ -115,31 +114,32 @@ replace_in_doc( "blob/master/docs/src/howToContribute.md" => "blob/master/.github/CONTRIBUTING.md", ) -# clean up notebooks -- we do not need to deploy all the stuff that was +# clean up examples -- we do not need to deploy all the stuff that was # generated in the process # # extra fun: failing programs (such as plotting libraries) may generate core # dumps that contain the dumped environment strings, which in turn contain # github auth tokens. These certainly need to be avoided. -notebooks_names = [n[begin:end-3] for n in notebooks_basenames] -ipynb_names = notebooks_names .* ".ipynb" -notebooks_allowed_files = vcat("index.html", ipynb_names) -@info "allowed files:" notebooks_allowed_files -for (root, dirs, files) in walkdir(joinpath(@__DIR__, "build", "notebooks")) +examples_names = [n[begin:end-3] for n in examples_basenames] +ipynb_names = examples_names .* ".ipynb" +examples_allowed_files = vcat("index.html", ipynb_names) +@info "allowed files:" examples_allowed_files +for (root, dirs, files) in walkdir(joinpath(@__DIR__, "build", "examples")) for f in files - if !(f in notebooks_allowed_files) + if !(f in examples_allowed_files) @info "removing notebook build artifact `$(joinpath(root, f))'" rm(joinpath(root, f)) end end end -# also remove the index template +# remove the template files rm(joinpath(@__DIR__, "build", "index.md.template")) +rm(joinpath(@__DIR__, "build", "quickstart.md.template")) # Binder actually has 1.6.2 kernel (seen in October 2021), but for whatever # reason it's called julia-1.1. Don't ask me. -for ipynb in joinpath.(@__DIR__, "build", "notebooks", ipynb_names) +for ipynb in joinpath.(@__DIR__, "build", "examples", ipynb_names) @info "changing julia version to 1.1 in `$ipynb'" js = JSON.parsefile(ipynb) js["metadata"]["kernelspec"]["name"] = "julia-1.1" diff --git a/docs/src/examples.md b/docs/src/examples.md new file mode 100644 index 000000000..c1f041c58 --- /dev/null +++ b/docs/src/examples.md @@ -0,0 +1,7 @@ + +# Example workflow and notebooks + +```@contents +Pages = filter(x -> endswith(x, ".md"), readdir("examples", join=true)) +Depth = 2 +``` diff --git a/docs/src/functions/analysis.md b/docs/src/functions/analysis.md index f37bbaa36..c65c185e1 100644 --- a/docs/src/functions/analysis.md +++ b/docs/src/functions/analysis.md @@ -4,19 +4,19 @@ ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("analysis", file), readdir("../src/analysis")) +Pages = readdir("../src/analysis", join=true) ``` ## Sampling ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("analysis", "sampling", file), readdir("../src/analysis/sampling")) +Pages = readdir("../src/analysis/sampling", join=true) ``` ## Analysis modifiers ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("analysis", "modifications", file), readdir("../src/analysis/modifications")) +Pages = readdir("../src/analysis/modifications", join=true) ``` diff --git a/docs/src/functions/base.md b/docs/src/functions/base.md index eff4308b7..becfbc7cb 100644 --- a/docs/src/functions/base.md +++ b/docs/src/functions/base.md @@ -2,5 +2,5 @@ ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("base", file), readdir("../src/base")) +Pages = readdir("../src/base", join=true) ``` diff --git a/docs/src/functions/io.md b/docs/src/functions/io.md index c7d908914..b919ccd3e 100644 --- a/docs/src/functions/io.md +++ b/docs/src/functions/io.md @@ -4,12 +4,12 @@ ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("io", file), readdir("../src/io")) +Pages = readdir("../src/io", join=true) ``` ## Pretty printing ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("io", "show", file), readdir("../src/io/show")) +Pages = readdir("../src/io/show", join=true) ``` diff --git a/docs/src/functions/reconstruction.md b/docs/src/functions/reconstruction.md index f85bddaf9..54b9539bc 100644 --- a/docs/src/functions/reconstruction.md +++ b/docs/src/functions/reconstruction.md @@ -4,12 +4,12 @@ ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("reconstruction", file), readdir("../src/reconstruction")) +Pages = readdir("../src/reconstruction", join=true) ``` ## Variant specifiers ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("reconstruction", "modifications", file), readdir("../src/reconstruction/modifications")) +Pages = readdir("../src/reconstruction/modifications", join=true) ``` diff --git a/docs/src/functions/types.md b/docs/src/functions/types.md index c952444c3..a94063ac7 100644 --- a/docs/src/functions/types.md +++ b/docs/src/functions/types.md @@ -4,17 +4,17 @@ ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("base", "types", "abstract", file), readdir("../src/base/types/abstract")) +Pages = readdir("../src/base/types/abstract", join=true) ``` ## Model types and contents ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("base", "types", file), readdir("../src/base/types")) +Pages = readdir("../src/base/types", join=true) ``` ## Model type wrappers ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("base", "types", "wrappers", file), readdir("../src/base/types/wrappers")) +Pages = readdir("../src/base/types/wrappers", join=true) ``` diff --git a/docs/src/functions/utils.md b/docs/src/functions/utils.md index b38635b54..29a868685 100644 --- a/docs/src/functions/utils.md +++ b/docs/src/functions/utils.md @@ -4,19 +4,19 @@ ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("base", "utils", file), readdir("../src/base/utils")) +Pages = readdir("../src/base/utils", join=true) ``` ## Macro-generated functions and internal helpers ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("base", "macros", file), readdir("../src/base/macros")) +Pages = readdir("../src/base/macros", join=true) ``` ## Logging and debugging helpers ```@autodocs Modules = [COBREXA] -Pages = map(file -> joinpath("base", "logging", file), readdir("../src/base/logging")) +Pages = readdir("../src/base/logging", join=true) ``` diff --git a/docs/src/index.md.template b/docs/src/index.md.template index 1e35d3737..a731036cf 100644 --- a/docs/src/index.md.template +++ b/docs/src/index.md.template @@ -44,19 +44,20 @@ analysis with COBREXA.jl. ## Example notebooks and workflows -Detailed notebook content is [available here](notebooks.md). +Detailed example listing is [available here](examples.md). +All examples are also avaialble as JuPyteR notebooks. ```@contents -Pages = joinpath.("notebooks", filter(x -> endswith(x, ".md"), readdir("notebooks"))) +Pages = filter(x -> endswith(x, ".md"), readdir("examples", join=true)) Depth = 1 ``` ## Core concept documentation -Detailed concept documentation content is [available here](tutorials.md). +Detailed concept guide listing is [available here](tutorials.md). ```@contents -Pages = joinpath.("tutorials", filter(x -> endswith(x, ".md"), readdir("tutorials"))) +Pages = filter(x -> endswith(x, ".md"), readdir("tutorials", join=true)) Depth = 1 ```