Examples workflow

.github/workflows/CI.yml

@@ -53,6 +53,10 @@ jobs:
       - uses: julia-actions/setup-julia@v1
         with:
           version: '1'
+      - uses: julia-actions/cache@v1
+        with:
+          cache-registries: "true"
+          cache-compiled: "true"
       - name: Configure doc environment
         run: |
           julia --project=docs/ -e '

.gitignore

@@ -6,3 +6,4 @@
 /docs/build/
 /test/Manifest.toml
 .vscode
+/docs/src/generated/*.md

docs/Project.toml

@@ -4,5 +4,6 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Gmsh = "705231aa-382f-11e9-3f0c-b7cb4346fdeb"
 HMatrices = "8646bddf-ab1c-4fa7-9c51-ba187d647618"
 Inti = "fb74042b-437e-4c5b-88cf-d4e2beb394d5"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 WriteVTK = "64499a7a-5c06-52f2-abe2-ccb03c286192"

docs/make.jl

@@ -1,38 +1,56 @@
 using Inti
 using Documenter
-
-# load package needed for extensions
+using Literate
+# packages needed for extensions
 using Gmsh
 using WriteVTK
 using CairoMakie
 using HMatrices
 
-DocMeta.setdocmeta!(Inti, :DocTestSetup, :(using Inti); recursive=true)
+# Generate examples using Literate
+const examples_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "examples")
+const generated_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "examples", "generated")
+example = "mock_example.jl"
+for example in ["mock_example.jl"]
+    src = joinpath(examples_dir, example)
+    Literate.markdown(src, generated_dir; mdstrings = true)
+    Literate.notebook(src, generated_dir; mdstrings = true)
+end
+
+## setup documentation config
+DocMeta.setdocmeta!(Inti, :DocTestSetup, :(using Inti); recursive = true)
+
+modules = [Inti]
+for extension in [:IntiGmshExt, :IntiMakieExt, :IntiVTKExt, :IntiHMatricesExt]
+    ext = Base.get_extension(Inti, extension)
+    isnothing(ext) && "error loading $ext"
+    push!(modules, ext)
+end
+
+# some settings are only active on a CI build
+on_CI = get(ENV, "CI", "false") == "true"
 
 makedocs(;
-    modules=[
-        Inti,
-    ],
-    authors="Luiz M. Faria",
-    repo="",
-    sitename="Inti.jl",
-    format=Documenter.HTML(;
-        prettyurls=get(ENV, "CI", "false") == "true",
-        canonical="https://IntegralEquations.github.io/Inti.jl",
-        edit_link="main",
+    modules = modules,
+    repo = "",
+    sitename = "Inti.jl",
+    format = Documenter.HTML(;
+        prettyurls = on_CI,
+        canonical = "https://IntegralEquations.github.io/Inti.jl",
+        edit_link = "main",
     ),
-    pages=[
+    pages = [
         "Home" => "index.md",
         "Meshing" => "geo_and_meshes.md",
-        "Examples" =>[
-            "examples/helmholtz_soundsoft_scattering_circle.md"
-        ],
+        "Examples" => ["examples/generated/mock_example.md"],
         "References" => "references.md",
     ],
+    warnonly = on_CI ? false : Documenter.except(:linkcheck_remotes),
     pagesonly = true,
 )
 
 deploydocs(;
-    repo="github.com/IntegralEquations/Inti.jl",
-    devbranch="main",
+    repo = "github.com/IntegralEquations/Inti.jl",
+    devbranch = "main",
+    push_preview = false,
 )

docs/src/examples/mock_example.jl

@@ -0,0 +1,22 @@
+import Pkg               #src
+docsdir = joinpath(@__DIR__,"../..") #src
+Pkg.activate(docsdir) #src
+
+md"""
+# Mock example
+"""
+
+#md # [![ipynb](https://img.shields.io/badge/download-ipynb-blue)](mock_example.ipynb)
+#md # [![nbviewer](https://img.shields.io/badge/show-nbviewer-blue.svg)](@__NBVIEWER_ROOT_URL__/examples/generated/mock_example.ipynb)
+
+md"""
+
+Testing how to use `Literate.jl` with `Documenter.jl` to generate documentation.
+
+!!! note "Mock admonition"
+    - This should work using `Documenter Markdown` syntax
+    - If it does not, check back again
+
+"""
+
+using Inti