Merge remote-tracking branch 'origin/master' into mhauru/change-gibbs…

…-sampler

.github/workflows/Docs.yml

@@ -0,0 +1,37 @@
+name: Documentation
+
+on:
+ push:
+ branches:
+ - master
+ tags: '*'
+ pull_request:
+ branches:
+ - master
+
+concurrency:
+ # Skip intermediate builds: always.
+ # Cancel intermediate builds: only if it is a pull request build.
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+permissions:
+ contents: write
+ pull-requests: read
+ statuses: write
+
+jobs:
+ docs:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: julia-actions/setup-julia@latest
+ with:
+ version: '1'
+ - name: Install dependencies
+ run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+ - name: Build and deploy
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+ run: julia --project=docs/ docs/make.jl

.github/workflows/DocsNav.yml

@@ -0,0 +1,49 @@
+name: Add Navbar
+
+on:
+ page_build: # Triggers the workflow on push events to gh-pages branch
+ workflow_dispatch: # Allows manual triggering
+ schedule:
+ - cron: '0 0 * * 0' # Runs every week on Sunday at midnight (UTC)
+
+jobs:
+ add-navbar:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - name: Checkout gh-pages
+ uses: actions/checkout@v4
+ with:
+ ref: gh-pages
+ fetch-depth: 0
+
+ - name: Download insert_navbar.sh
+ run: |
+ curl -O https://raw.githubusercontent.com/TuringLang/turinglang.github.io/main/assets/scripts/insert_navbar.sh
+ chmod +x insert_navbar.sh
+
+ - name: Update Navbar
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ git config user.name github-actions[bot]
+ git config user.email github-actions[bot]@users.noreply.github.com
+
+ # Define the URL of the navbar to be used
+ NAVBAR_URL="https://raw.githubusercontent.com/TuringLang/turinglang.github.io/main/assets/scripts/TuringNavbar.html"
+ 
+ # Update all HTML files in the current directory (gh-pages root)
+ ./insert_navbar.sh . $NAVBAR_URL
+ 
+ # Remove the insert_navbar.sh file
+ rm insert_navbar.sh
+ 
+ # Check if there are any changes
+ if [[ -n $(git status -s) ]]; then
+ git add .
+ git commit -m "Added navbar and removed insert_navbar.sh"
+ git push "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" gh-pages
+ else
+ echo "No changes to commit"
+ fi

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Bijectors = "76274a88-744f-5084-9051-94815aaf08c4"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+Turing = "fce5fe82-541a-59a6-adf8-730c64b5f9a0"

docs/make.jl

@@ -0,0 +1,37 @@
+using Documenter
+using Turing
+# Need to import Distributions and Bijectors to generate docs for functions
+# from those packages.
+using Distributions
+using Bijectors
+
+using DocumenterInterLinks
+
+links = InterLinks(
+ "DynamicPPL" => "https://turinglang.org/DynamicPPL.jl/stable/objects.inv",
+ "AbstractPPL" => "https://turinglang.org/AbstractPPL.jl/dev/objects.inv",
+ "ADTypes" => "https://sciml.github.io/ADTypes.jl/stable/objects.inv",
+ "AdvancedVI" => "https://turinglang.org/AdvancedVI.jl/v0.2.8/objects.inv",
+ "DistributionsAD" => "https://turinglang.org/DistributionsAD.jl/stable/objects.inv",
+)
+
+# Doctest setup
+DocMeta.setdocmeta!(Turing, :DocTestSetup, :(using Turing); recursive=true)
+
+makedocs(;
+ sitename="Turing",
+ modules=[Turing, Distributions, Bijectors],
+ pages=[
+ "Home" => "index.md",
+ "API" => "api.md",
+ "Submodule APIs" =>
+ ["Inference" => "api/Inference.md", "Optimisation" => "api/Optimisation.md"],
+ ],
+ checkdocs=:exports,
+ # checkdocs_ignored_modules=[Turing, Distributions, DynamicPPL, AbstractPPL, Bijectors],
+ doctest=false,
+ warnonly=true,
+ plugins=[links],
+)
+
+deploydocs(; repo="github.com/TuringLang/Turing.jl.git", push_preview=true)

docs/src/api.md

@@ -0,0 +1,170 @@
+# API
+
+## Module-wide re-exports
+
+Turing.jl directly re-exports the entire public API of the following packages:
+
+ - [Distributions.jl](https://juliastats.org/Distributions.jl)
+ - [MCMCChains.jl](https://turinglang.org/MCMCChains.jl)
+ - [AbstractMCMC.jl](https://turinglang.org/AbstractMCMC.jl)
+ - [Bijectors.jl](https://turinglang.org/Bijectors.jl)
+ - [Libtask.jl](https://github.com/TuringLang/Libtask.jl)
+
+Please see the individual packages for their documentation.
+
+## Individual exports and re-exports
+
+**All** of the following symbols are exported unqualified by Turing, even though the documentation suggests that many of them are qualified.
+That means, for example, you can just write
+
+```julia
+using Turing
+
+@model function my_model() end
+
+sample(my_model(), Prior(), 100)
+```
+
+instead of
+
+```julia
+DynamicPPL.@model function my_model() end
+
+sample(my_model(), Turing.Inference.Prior(), 100)
+```
+
+even though [`Prior()`](@ref) is actually defined in the `Turing.Inference` module and [`@model`](@ref) in the `DynamicPPL` package.
+
+### Modelling
+
+| Exported symbol | Documentation | Description |
+|:--------------- |:--------------------------------- |:-------------------------------------------- |
+| `@model` | [`DynamicPPL.@model`](@extref) | Define a probabilistic model |
+| `@varname` | [`AbstractPPL.@varname`](@extref) | Generate a `VarName` from a Julia expression |
+| `@submodel` | [`DynamicPPL.@submodel`](@extref) | Define a submodel |
+
+### Inference
+
+| Exported symbol | Documentation | Description |
+|:--------------- |:------------------------------------------------------------------------------------------------ |:------------------- |
+| `sample` | [`StatsBase.sample`](https://turinglang.org/AbstractMCMC.jl/stable/api/#Sampling-a-single-chain) | Sample from a model |
+
+### Samplers
+
+| Exported symbol | Documentation | Description |
+|:-------------------- |:--------------------------------------------- |:------------------------------------------------------------------- |
+| `Prior` | [`Turing.Inference.Prior`](@ref) | Sample from the prior distribution |
+| `MH` | [`Turing.Inference.MH`](@ref) | Metropolis–Hastings |
+| `Emcee` | [`Turing.Inference.Emcee`](@ref) | Affine-invariant ensemble sampler |
+| `ESS` | [`Turing.Inference.ESS`](@ref) | Elliptical slice sampling |
+| `Gibbs` | [`Turing.Inference.Gibbs`](@ref) | Gibbs sampling |
+| `GibbsConditional` | [`Turing.Inference.GibbsConditional`](@ref) | A "pseudo-sampler" to provide analytical conditionals to `Gibbs` |
+| `HMC` | [`Turing.Inference.HMC`](@ref) | Hamiltonian Monte Carlo |
+| `SGLD` | [`Turing.Inference.SGLD`](@ref) | Stochastic gradient Langevin dynamics |
+| `SGHMC` | [`Turing.Inference.SGHMC`](@ref) | Stochastic gradient Hamiltonian Monte Carlo |
+| `PolynomialStepsize` | [`Turing.Inference.PolynomialStepsize`](@ref) | Returns a function which generates polynomially decaying step sizes |
+| `HMCDA` | [`Turing.Inference.HMCDA`](@ref) | Hamiltonian Monte Carlo with dual averaging |
+| `NUTS` | [`Turing.Inference.NUTS`](@ref) | No-U-Turn Sampler |
+| `IS` | [`Turing.Inference.IS`](@ref) | Importance sampling |
+| `SMC` | [`Turing.Inference.SMC`](@ref) | Sequential Monte Carlo |
+| `PG` | [`Turing.Inference.PG`](@ref) | Particle Gibbs |
+| `CSMC` | [`Turing.Inference.CSMC`](@ref) | The same as PG |
+| `externalsampler` | [`Turing.Inference.externalsampler`](@ref) | Wrap an external sampler for use in Turing |
+
+### Variational inference
+
+See the [variational inference tutorial](https://turinglang.org/docs/tutorials/09-variational-inference/) for a walkthrough on how to use these.
+
+| Exported symbol | Documentation | Description |
+|:--------------- |:---------------------------- |:--------------------------------------- |
+| `vi` | [`AdvancedVI.vi`](@extref) | Perform variational inference |
+| `ADVI` | [`AdvancedVI.ADVI`](@extref) | Construct an instance of a VI algorithm |
+
+### Automatic differentiation types
+
+These are used to specify the automatic differentiation backend to use.
+See the [AD guide](https://turinglang.org/docs/tutorials/docs-10-using-turing-autodiff/) for more information.
+
+| Exported symbol | Documentation | Description |
+|:----------------- |:------------------------------------ |:----------------------------------------- |
+| `AutoForwardDiff` | [`ADTypes.AutoForwardDiff`](@extref) | ForwardDiff.jl backend |
+| `AutoReverseDiff` | [`ADTypes.AutoReverseDiff`](@extref) | ReverseDiff.jl backend |
+| `AutoZygote` | [`ADTypes.AutoZygote`](@extref) | Zygote.jl backend |
+| `AutoTracker` | [`ADTypes.AutoTracker`](@extref) | Tracker.jl backend |
+| `AutoTapir` | [`ADTypes.AutoTapir`](@extref) | Tapir.jl backend, only for ADTypes >= 1.0 |
+
+### Debugging
+
+```@docs
+setprogress!
+```
+
+### Distributions
+
+These distributions are defined in Turing.jl, but not in Distributions.jl.
+
+```@docs
+Flat
+FlatPos
+BinomialLogit
+OrderedLogistic
+LogPoisson
+```
+
+`BernoulliLogit` is part of Distributions.jl since version 0.25.77.
+If you are using an older version of Distributions where this isn't defined, Turing will export the same distribution.
+
+```@docs
+Distributions.BernoulliLogit
+```
+
+### Tools to work with distributions
+
+| Exported symbol | Documentation | Description |
+|:--------------- |:-------------------------------------- |:-------------------------------------------------------------- |
+| `filldist` | [`DistributionsAD.filldist`](@extref) | Create a product distribution from a distribution and integers |
+| `arraydist` | [`DistributionsAD.arraydist`](@extref) | Create a product distribution from an array of distributions |
+| `NamedDist` | [`DynamicPPL.NamedDist`](@extref) | A distribution that carries the name of the variable |
+
+### Predictions
+
+```@docs
+predict
+```
+
+### Querying model probabilities and quantities
+
+Please see the [generated quantities](https://turinglang.org/docs/tutorials/usage-generated-quantities/) and [probability interface](https://turinglang.org/docs/tutorials/usage-probability-interface/) guides for more information.
+
+| Exported symbol | Documentation | Description |
+|:-------------------------- |:--------------------------------------------------------------------------------------------------------------------------------- |:--------------------------------------------------------------- |
+| `generated_quantities` | [`DynamicPPL.generated_quantities`](@extref) | Calculate additional quantities defined in a model |
+| `pointwise_loglikelihoods` | [`DynamicPPL.pointwise_loglikelihoods`](@extref) | Compute log likelihoods for each sample in a chain |
+| `logprior` | [`DynamicPPL.logprior`](@extref) | Compute log prior probability |
+| `logjoint` | [`DynamicPPL.logjoint`](@extref) | Compute log joint probability |
+| `LogDensityFunction` | [`DynamicPPL.LogDensityFunction`](@extref) | Wrap a Turing model to satisfy LogDensityFunctions.jl interface |
+| `condition` | [`AbstractPPL.condition`](@extref) | Condition a model on data |
+| `decondition` | [`AbstractPPL.decondition`](@extref) | Remove conditioning on data |
+| `conditioned` | [`DynamicPPL.conditioned`](@extref) | Return the conditioned values of a model |
+| `fix` | [`DynamicPPL.fix`](@extref) | Fix the value of a variable |
+| `unfix` | [`DynamicPPL.unfix`](@extref) | Unfix the value of a variable |
+| `OrderedDict` | [`OrderedCollections.OrderedDict`](https://juliacollections.github.io/OrderedCollections.jl/dev/ordered_containers/#OrderedDicts) | An ordered dictionary |
+
+### Extra re-exports from Bijectors
+
+Note that Bijectors itself does not export `ordered`.
+
+```@docs
+Bijectors.ordered
+```
+
+### Point estimates
+
+See the [mode estimation tutorial](https://turinglang.org/docs/tutorials/docs-17-mode-estimation/) for more information.
+
+| Exported symbol | Documentation | Description |
+|:---------------------- |:-------------------------------------------------- |:-------------------------------------------- |
+| `maximum_a_posteriori` | [`Turing.Optimisation.maximum_a_posteriori`](@ref) | Find a MAP estimate for a model |
+| `maximum_likelihood` | [`Turing.Optimisation.maximum_likelihood`](@ref) | Find a MLE estimate for a model |
+| `MAP` | [`Turing.Optimisation.MAP`](@ref) | Type to use with Optim.jl for MAP estimation |
+| `MLE` | [`Turing.Optimisation.MLE`](@ref) | Type to use with Optim.jl for MLE estimation |

docs/src/api/Inference.md

@@ -0,0 +1,6 @@
+# API: `Turing.Inference`
+
+```@autodocs
+Modules = [Turing.Inference]
+Order = [:type, :function]
+```

docs/src/api/Optimisation.md

@@ -0,0 +1,6 @@
+# API: `Turing.Optimisation`
+
+```@autodocs
+Modules = [Turing.Optimisation]
+Order = [:type, :function]
+```

docs/src/index.md

@@ -0,0 +1,5 @@
+# Turing.jl
+
+This site contains the API documentation for the identifiers exported by Turing.jl.
+
+If you are looking for usage examples and guides, please visit [https://turinglang.org/docs](https://turinglang.org/docs).