Export predict with 0.35 (#821)

* export `predict`

* use mcmcchains when build doc

* Apply suggestions from code review

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Add MCMCChainsExt to docs build (#822)

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Penelope Yong <penelopeysm@gmail.com>

Author: 3 people

docs/make.jl

@@ -9,16 +9,20 @@ using DynamicPPL: AbstractPPL
 # consistent with that.
 using Distributions
 using DocumenterMermaid
+# load MCMCChains package extension to make `predict` available
+using MCMCChains
 
 # Doctest setup
-DocMeta.setdocmeta!(DynamicPPL, :DocTestSetup, :(using DynamicPPL); recursive=true)
+DocMeta.setdocmeta!(
+    DynamicPPL, :DocTestSetup, :(using DynamicPPL, MCMCChains); recursive=true
+)
 
 makedocs(;
     sitename="DynamicPPL",
     # The API index.html page is fairly large, and violates the default HTML page size
     # threshold of 200KiB, so we double that.
     format=Documenter.HTML(; size_threshold=2^10 * 400),
-    modules=[DynamicPPL],
+    modules=[DynamicPPL, Base.get_extension(DynamicPPL, :DynamicPPLMCMCChainsExt)],
     pages=[
         "Home" => "index.md", "API" => "api.md", "Internals" => ["internals/varinfo.md"]
     ],

docs/src/api.md

@@ -104,6 +104,32 @@ Similarly, we can [`unfix`](@ref) variables, i.e. return them to their original
 unfix
 ```
 
+## Predicting
+
+DynamicPPL provides functionality for generating samples from the posterior predictive distribution through the `predict` function. This allows you to use posterior parameter samples to generate predictions for unobserved data points.
+
+The `predict` function has two main methods:
+
+ 1. For `AbstractVector{<:AbstractVarInfo}` - useful when you have a collection of `VarInfo` objects representing posterior samples.
+ 2. For `MCMCChains.Chains` (only available when `MCMCChains.jl` is loaded) - useful when you have posterior samples in the form of an `MCMCChains.Chains` object.
+
+```@docs
+predict
+```
+
+### Basic Usage
+
+The typical workflow for posterior prediction involves:
+
+ 1. Fitting a model to observed data to obtain posterior samples
+ 2. Creating a new model instance with some variables marked as missing (unobserved)
+ 3. Using `predict` to generate samples for these missing variables based on the posterior parameter samples
+
+When using `predict` with `MCMCChains.Chains`, you can control which variables are included in the output with the `include_all` parameter:
+
+  - `include_all=false` (default): Include only newly predicted variables
+  - `include_all=true`: Include both parameters from the original chain and predicted variables
+
 ## Models within models
 
 One can include models and call another model inside the model function with `left ~ to_submodel(model)`.

src/DynamicPPL.jl

@@ -115,6 +115,7 @@ export AbstractVarInfo,
     decondition,
     fix,
     unfix,
+    predict,
     prefix,
     returned,
     to_submodel,