Generate API docs (#2347)

* Add workflows * Add API docs * Format * Add link to [email protected] docs * Format Markdown table right Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Correct MH docstrings * Add more links to the main docs * Fix introductory example * Add links to DistributionsAD docs * Bump actions/checkout version Co-authored-by: Xianda Sun <[email protected]> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Xianda Sun <[email protected]>
TuringLang · Oct 13, 2024 · 24e6870 · 24e6870
1 parent 40a0d84
commit 24e6870
Show file tree

Hide file tree

Showing 19 changed files with 367 additions and 152 deletions.
diff --git a/.github/workflows/Docs.yml b/.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
diff --git a/.github/workflows/DocsNav.yml b/.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
diff --git a/docs/Project.toml b/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"
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/make.jl b/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)
diff --git a/docs/src/api.md b/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 |
diff --git a/docs/src/api/Inference.md b/docs/src/api/Inference.md
@@ -0,0 +1,6 @@
+# API: `Turing.Inference`
+
+```@autodocs
+Modules = [Turing.Inference]
+Order  = [:type, :function]
+```
diff --git a/docs/src/api/Optimisation.md b/docs/src/api/Optimisation.md
@@ -0,0 +1,6 @@
+# API: `Turing.Optimisation`
+
+```@autodocs
+Modules = [Turing.Optimisation]
+Order  = [:type, :function]
+```
diff --git a/docs/src/index.md b/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).
diff --git a/docs/src/library/advancedhmc.md b/docs/src/library/advancedhmc.md