building examples for documentation

README.md

@@ -22,7 +22,7 @@ running from this directory.
 Run an example:
 
 ```
-$ julia --project examples/example1.jl
+$ julia --project examples/sine.jl
 x
      I  COEFFICIENT              ORDER EXPONENTS
      1    1.0000000000000000e+00   1   1

docs/Project.toml

@@ -1,2 +1,3 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"

docs/make.jl

@@ -1,12 +1,50 @@
 push!(LOAD_PATH, joinpath(@__DIR__, ".."))
 
-using Documenter, DACE
+using Documenter
+using Literate
+using DACE
+
+# generate examples, based on https://github.com/CliMA/Oceananigans.jl/blob/1c2a6f8752b6425bf30d856f8ba0aa681c0ab818/docs/make.jl
+
+const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
+const OUTPUT_DIR = joinpath(@__DIR__, "src", "generated")
+
+example_scripts = [
+    "sine.jl",
+]
+
+println("Building examples...")
+for example in example_scripts
+    println("Building: $example")
+    example_filepath = joinpath(EXAMPLES_DIR, example)
+
+    Literate.markdown(example_filepath, OUTPUT_DIR;
+                      flavor = Literate.DocumenterFlavor(), execute = true)
+end
+println("Finished building examples")
+
+# organise pages
+
+example_pages = [
+    "Sine function" => "generated/sine.md",
+]
+
+pages = [
+    "Home" => "index.md",
+    "Examples" => example_pages,
+]
+
+# build and deploy docs
+
+format = Documenter.HTML(
+    prettyurls = get(ENV, "CI", nothing) == "true",
+)
 
 makedocs(
-    sitename="DACE.jl",
-    format = Documenter.HTML(
-        prettyurls = get(ENV, "CI", nothing) == "true",
-    ),
+    sitename = "DACE.jl",
+    format = format,
+    pages = pages,
+#    modules = [DACE],
 )
 
 deploydocs(

docs/src/index.md

@@ -16,13 +16,17 @@ pkg> add https://github.com/chrisdjscott/DACE_jll.jl.git
 pkg> add https://github.com/chrisdjscott/DACE.jl.git
 ```
 
+Note: the second `add` command above may not be needed if you are
+running from main directory of the repository.
+
 ## Notes about the interface
 
 - The Julia interface is built using [CxxWrap.jl](https://github.com/JuliaInterop/CxxWrap.jl)
 - The C++ source for the interface is currently in [this fork](https://github.com/chrisdjscott/dace/tree/julia-interface/interfaces/julia)
   of the DACE library
-- The C++ code gets built and released to the DACE\_jll package, currently located
-  [here](https://github.com/chrisdjscott/DACE_jll.jl)
+- The C++ code gets built and released to the DACE\_jll package
+  - DACE\_jll is located [here](https://github.com/chrisdjscott/DACE_jll.jl)
+  - the build recipe is currently [here](https://github.com/chrisdjscott/Yggdrasil/tree/beacbce0777417d58d748729e5bc1ab73604aa93/D/DACE)
 - The Julia component of the interface is currently [here](https://github.com/chrisdjscott/DACE.jl)
 
 The above may change, in particular we hope to:

examples/sine.jl

@@ -0,0 +1,52 @@
+# # Sine example
+#
+# This is a simple DACE example using the sine function, which demonstrates:
+#
+# - How to load DACE.jl
+# - How to initialise the DACE library
+# - How to create a `DA` object
+# - How to compute the sine of a `DA` object
+# - How to print a `DA` object to screen
+# - How to evaluate a `DA` object
+#
+# ## Install dependencies
+#
+# Make sure the required packages are installed
+
+# ```julia
+# using Pkg
+# Pkg.add("https://github.com/chrisdjscott/DACE_jll.jl.git")
+# Pkg.add("https://github.com/chrisdjscott/DACE.jl.git")
+# ```
+
+# ## Using DACE
+#
+# Write
+
+using DACE
+
+# to load DACE functions and objects into our script.
+#
+# Initialise DACE for 20th-order computations in 1 variable
+
+DACE.init(20, 1)
+
+# Initialise `x` as a `DA` object
+
+x = DACE.DA(1)
+
+# Initialise `y` as the Taylor expansion of `sin(x)`
+
+y = sin(x)
+
+# Print `x` and `y` to screen
+
+println("x")
+print(x)
+println("y = sin(x)")
+print(y)
+
+# Evaluate `y` at 1.0 and compare with the builtin `sin` function.
+
+println("  y(1.0) = $(DACE.evalScalar(y, 1.0))")
+println("sin(1.0) = $(sin(1.0))")