Reorganize documentation.

probcomp · Oct 5, 2024 · 614a10a · 614a10a
1 parent ff2deec
commit 614a10a
Show file tree

Hide file tree

Showing 51 changed files with 1,070 additions and 1,488 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -1,17 +1,18 @@
-# Website Docs
-- `pages.jl` to find skeleton of website.
-- `make.jl` to build the website index.
+# Gen.jl Documentation
 
-The docs are divided in roughly four sections:
+- `pages.jl` to find skeleton of the Gen.jl documentation.
+- `make.jl` to build the documentation website index.
+
+The documentation is divided into three sections:
 - Getting Started + Tutorials
 - How-to Guides
-- API = Modeling API + Inference API
-- Explanations + Internals
-
+- Reference Guides
 
 # Developing
-To build the docs, run `julia --make.jl` or alternatively startup the Julia REPL and include `make.jl`. For debugging, consider setting `draft=true` in the `makedocs` function found in `make.jl`.
-Currently you must write the tutorial directly in the docs rather than a source file (e.g. Quarto). See `getting_started` or `tutorials` for examples.
+
+To build the docs, run `julia --make.jl`. Alternatively, start the Julia REPL, activate the `Project.toml` in this directory, then include `make.jl`. For debugging, consider setting `draft=true` in the `makedocs` function found in `make.jl`. This will avoid running the `@example` blocks when generating the tutorials.
+
+Currently you must write the tutorial directly in the docs rather than in a source file. See `tutorials` for examples.
 
 Code snippets must use the triple backtick with a label to run. The environment carries over so long as the labels match. Example:
 
@@ -21,4 +22,4 @@ x = rand()
 
 ```@example tutorial_1
 print(x)
-```
+```
diff --git a/docs/make.jl b/docs/make.jl
@@ -8,7 +8,6 @@ makedocs(
     clean = true,
     warnonly = true,
     format = Documenter.HTML(;
-        assets = String["assets/header.js", "assets/header.css", "assets/theme.css"],
         collapselevel=1,
     ),
     sitename = "Gen.jl",

diff --git a/docs/pages.jl b/docs/pages.jl
@@ -1,53 +1,45 @@
 pages = [
-    "Home" => "index.md",
-    "Getting Started" => [
-        "Example 1: Linear Regression" => "getting_started/linear_regression.md",
-    ],
+    "Gen.jl" => "index.md",
     "Tutorials" => [
-        "Basics" => [
-            "tutorials/basics/modeling_in_gen.md",
-            "tutorials/basics/gfi.md",
-            "tutorials/basics/combinators.md",
-            "tutorials/basics/particle_filter.md",
-            "tutorials/basics/vi.md",
-        ],
-        "Advanced" => [
-            "tutorials/trace_translators.md",
-        ],
-        "Model Optmizations" => [
-            "Speeding Inference with the Static Modeling Language" => "tutorials/model_optimizations/scaling_with_sml.md",
-        ],
+        "Getting Started" => "tutorials/getting_started.md",
+        "Introduction to Modeling in Gen" => "tutorials/modeling_in_gen.md",
+        "Object Tracking with SMC" => "tutorials/smc.md",
+        "Learning Generative Functions" => "tutorials/learning_gen_fns.md",
+        "Speeding Up Inference with the SML" => "tutorials/scaling_with_sml.md",
     ],
     "How-to Guides" => [
-        "MCMC Kernels" => "how_to/mcmc_kernels.md",
-        "Custom Distributions" => "how_to/custom_distributions.md",
-        "Custom Modeling Languages" => "how_to/custom_dsl.md",
-        "Custom Gradients" => "how_to/custom_derivatives.md",
-        "Incremental Computation" => "how_to/custom_incremental_computation.md",
+        "Extending Gen" => "how_to/extending_gen.md",
+        "Adding New Distributions" => "how_to/custom_distributions.md",
+        "Adding New Generative Functions" => "how_to/custom_gen_fns.md",
+        "Custom Gradients" => "how_to/custom_gradients.md",
+        "Custom Incremental Computation" => "how_to/custom_incremental_computation.md",
     ],
-    "API Reference" => [
+    "Reference" => [
+        "Core Interfaces" => [
+            "Generative Function Interface" => "ref/core/gfi.md",
+            "Choice Maps" => "ref/core/choice_maps.md",
+            "Selections" => "ref/core/selections.md",
+            "Change Hints" => "ref/core/change_hints.md",
+        ],
         "Modeling Library" => [
-            "Generative Functions" => "api/model/gfi.md",
-            "Probability Distributions" => "api/model/distributions.md",
-            "Choice Maps" => "api/model/choice_maps.md",
-            "Built-in Modeling Languages" => "api/model/modeling.md",
-            "Combinators" => "api/model/combinators.md",
-            "Selections" => "api/model/selections.md",
-            "Optimizing Trainable Parameters" => "api/model/parameter_optimization.md",
-            "Trace Translators" => "api/model/trace_translators.md",
+            "Built-In Modeling Language" => "ref/modeling/dml.md",
+            "Static Modeling Language" => "ref/modeling/sml.md",
+            "Probability Distributions" => "ref/modeling/distributions.md",
+            "Combinators" => "ref/modeling/combinators.md",
+            "Custom Generative Functions" => "ref/modeling/custom_gen_fns.md",
         ],
         "Inference Library" => [
-            "Importance Sampling" => "api/inference/importance.md",
-            "MAP Optimization" => "api/inference/map.md",
-            "Markov chain Monte Carlo" => "api/inference/mcmc.md",
-            "MAP Optimization" => "api/inference/map.md",
-            "Particle Filtering" => "api/inference/pf.md",
-            "Variational Inference" => "api/inference/vi.md",
-            "Learning Generative Functions" => "api/inference/learning.md"
+            "Importance Sampling" => "ref/inference/importance.md",
+            "Markov Chain Monte Carlo" => "ref/inference/mcmc.md",
+            "Particle Filtering & SMC" => "ref/inference/pf.md",
+            "Trace Translators" => "ref/inference/trace_translators.md",
+            "Parameter Optimization" => "ref/inference/parameter_optimization.md",
+            "MAP Optimization" => "ref/inference/map.md",
+            "Variational Inference" => "ref/inference/vi.md",
+            "Wake-Sleep Learning" => "ref/inference/wake_sleep.md",
         ],
+        "Internals" => [
+            "Modeling Language Implementation" => "ref/internals/language_implementation.md",
+        ]
     ],
-    "Explanation and Internals" => [
-        "Modeling Language Implementation" => "explanations/language_implementation.md",
-        "explanations/combinator_design.md"
-    ]
 ]
diff --git a/docs/src/api/inference/map.md b/docs/src/api/inference/map.md
diff --git a/docs/src/api/inference/mcmc.md b/docs/src/api/inference/mcmc.md
diff --git a/docs/src/api/inference/pf.md b/docs/src/api/inference/pf.md
diff --git a/docs/src/api/inference/vi.md b/docs/src/api/inference/vi.md
diff --git a/docs/src/api/model/gfi.md b/docs/src/api/model/gfi.md
diff --git a/docs/src/api/model/trace_translators.md b/docs/src/api/model/trace_translators.md
diff --git a/docs/src/assets/header.css b/docs/src/assets/header.css