Add an end-to-end OLS tutorial

Project.toml

@@ -1,6 +1,6 @@
 name = "JuliaLibWrapping"
 uuid = "d61f35a8-f6af-436f-bc10-cee6b101f7bd"
-version = "1.0.0-DEV"
+version = "0.1"
 authors = ["Tim Holy <tim.holy@gmail.com> and contributors"]
 
 [deps]

docs/make.jl

@@ -16,6 +16,7 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
+        "Tutorial" => "tutorial.md",
         "Concepts" => "concepts.md",
         "JLWInterop" => "jlwinterop.md",
         "Error handling" => "error_handling.md",

docs/src/index.md

@@ -11,10 +11,14 @@ It turns the ABI metadata that `juliac` emits into wrappers that let
 non-Julia programs call the compiled library as if it were any other
 native dependency.
 
+New to the package? Start with the [tutorial](@ref "Tutorial: wrap an
+OLS regression library") — it walks a small library end to end, from
+Julia source through `pip install` to numpy-flavored Python.
+
 ## Who it is for
 
-Authors of Julia libraries who want to ship a compiled artifact that
-downstream users — typically C or Python programmers — can consume
+Authors of Julia libraries who want to ship compiled code that
+downstream users — currently C or Python programmers — can use
 without installing a Julia runtime themselves. The compiled library is
 produced by `juliac`; this package produces the binding code that makes
 it usable from the target language.
@@ -36,13 +40,16 @@ bundling, multi-library, and two-tier output stories.
 
 ## Where to go next
 
-- [Concepts](@ref) — the pipeline, the ABI data model, the extension
+- [Tutorial: wrap an OLS regression library](@ref): build a small library with a
+  Python wrapper using numpy.
+- [Concepts](@ref): the pipeline, the ABI data model, the extension
   point for new target languages, and the runtime-closure / bundling
   story.
-- [JLWInterop](@ref) — the dependency-free vocabulary package
-  (`CVector`, `CMatrix`, `CString`, `JLWStatus`) that compiled
-  libraries and the Python emitter both speak.
-- [Error handling across the ABI](@ref) — the `JLWStatus` convention
+- [JLWInterop](@ref): a small package needed by almost any wrapped Julia module.
+  Defines a few interoperability types (`CArray`, `CString`, and `JLWStatus`)
+  that your Julia wrapper-code should use to ensure interopability with the
+  language binding.
+- [Error handling across the ABI](@ref): the `JLWStatus` convention
   that lets wrapped libraries surface errors as native exceptions in
   the target language.
-- [API reference](@ref) — generated docstrings for the public API.
+- [API reference](@ref): the public API, in full detail.