Skip to content

Commit 24e6870

Browse files
penelopeysmgithub-actions[bot]sunxd3
authored
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]>
1 parent 40a0d84 commit 24e6870

File tree

19 files changed

+367
-152
lines changed

19 files changed

+367
-152
lines changed

‎.github/workflows/Docs.yml

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
tags: '*'
8+
pull_request:
9+
branches:
10+
- master
11+
12+
concurrency:
13+
# Skip intermediate builds: always.
14+
# Cancel intermediate builds: only if it is a pull request build.
15+
group: ${{ github.workflow }}-${{ github.ref }}
16+
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
17+
18+
permissions:
19+
contents: write
20+
pull-requests: read
21+
statuses: write
22+
23+
jobs:
24+
docs:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- uses: actions/checkout@v4
28+
- uses: julia-actions/setup-julia@latest
29+
with:
30+
version: '1'
31+
- name: Install dependencies
32+
run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
33+
- name: Build and deploy
34+
env:
35+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
36+
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
37+
run: julia --project=docs/ docs/make.jl

‎.github/workflows/DocsNav.yml

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Add Navbar
2+
3+
on:
4+
page_build: # Triggers the workflow on push events to gh-pages branch
5+
workflow_dispatch: # Allows manual triggering
6+
schedule:
7+
- cron: '0 0 * * 0' # Runs every week on Sunday at midnight (UTC)
8+
9+
jobs:
10+
add-navbar:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: write
14+
steps:
15+
- name: Checkout gh-pages
16+
uses: actions/checkout@v4
17+
with:
18+
ref: gh-pages
19+
fetch-depth: 0
20+
21+
- name: Download insert_navbar.sh
22+
run: |
23+
curl -O https://raw.githubusercontent.com/TuringLang/turinglang.github.io/main/assets/scripts/insert_navbar.sh
24+
chmod +x insert_navbar.sh
25+
26+
- name: Update Navbar
27+
env:
28+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
29+
run: |
30+
git config user.name github-actions[bot]
31+
git config user.email github-actions[bot]@users.noreply.github.com
32+
33+
# Define the URL of the navbar to be used
34+
NAVBAR_URL="https://raw.githubusercontent.com/TuringLang/turinglang.github.io/main/assets/scripts/TuringNavbar.html"
35+
36+
# Update all HTML files in the current directory (gh-pages root)
37+
./insert_navbar.sh . $NAVBAR_URL
38+
39+
# Remove the insert_navbar.sh file
40+
rm insert_navbar.sh
41+
42+
# Check if there are any changes
43+
if [[ -n $(git status -s) ]]; then
44+
git add .
45+
git commit -m "Added navbar and removed insert_navbar.sh"
46+
git push "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" gh-pages
47+
else
48+
echo "No changes to commit"
49+
fi

‎docs/Project.toml

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

‎docs/README.md

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/make.jl

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
using Documenter
2+
using Turing
3+
# Need to import Distributions and Bijectors to generate docs for functions
4+
# from those packages.
5+
using Distributions
6+
using Bijectors
7+
8+
using DocumenterInterLinks
9+
10+
links = InterLinks(
11+
"DynamicPPL" => "https://turinglang.org/DynamicPPL.jl/stable/objects.inv",
12+
"AbstractPPL" => "https://turinglang.org/AbstractPPL.jl/dev/objects.inv",
13+
"ADTypes" => "https://sciml.github.io/ADTypes.jl/stable/objects.inv",
14+
"AdvancedVI" => "https://turinglang.org/AdvancedVI.jl/v0.2.8/objects.inv",
15+
"DistributionsAD" => "https://turinglang.org/DistributionsAD.jl/stable/objects.inv",
16+
)
17+
18+
# Doctest setup
19+
DocMeta.setdocmeta!(Turing, :DocTestSetup, :(using Turing); recursive=true)
20+
21+
makedocs(;
22+
sitename="Turing",
23+
modules=[Turing, Distributions, Bijectors],
24+
pages=[
25+
"Home" => "index.md",
26+
"API" => "api.md",
27+
"Submodule APIs" =>
28+
["Inference" => "api/Inference.md", "Optimisation" => "api/Optimisation.md"],
29+
],
30+
checkdocs=:exports,
31+
# checkdocs_ignored_modules=[Turing, Distributions, DynamicPPL, AbstractPPL, Bijectors],
32+
doctest=false,
33+
warnonly=true,
34+
plugins=[links],
35+
)
36+
37+
deploydocs(; repo="github.com/TuringLang/Turing.jl.git", push_preview=true)

‎docs/src/api.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# API
2+
3+
## Module-wide re-exports
4+
5+
Turing.jl directly re-exports the entire public API of the following packages:
6+
7+
- [Distributions.jl](https://juliastats.org/Distributions.jl)
8+
- [MCMCChains.jl](https://turinglang.org/MCMCChains.jl)
9+
- [AbstractMCMC.jl](https://turinglang.org/AbstractMCMC.jl)
10+
- [Bijectors.jl](https://turinglang.org/Bijectors.jl)
11+
- [Libtask.jl](https://github.com/TuringLang/Libtask.jl)
12+
13+
Please see the individual packages for their documentation.
14+
15+
## Individual exports and re-exports
16+
17+
**All** of the following symbols are exported unqualified by Turing, even though the documentation suggests that many of them are qualified.
18+
That means, for example, you can just write
19+
20+
```julia
21+
using Turing
22+
23+
@model function my_model() end
24+
25+
sample(my_model(), Prior(), 100)
26+
```
27+
28+
instead of
29+
30+
```julia
31+
DynamicPPL.@model function my_model() end
32+
33+
sample(my_model(), Turing.Inference.Prior(), 100)
34+
```
35+
36+
even though [`Prior()`](@ref) is actually defined in the `Turing.Inference` module and [`@model`](@ref) in the `DynamicPPL` package.
37+
38+
### Modelling
39+
40+
| Exported symbol | Documentation | Description |
41+
|:--------------- |:--------------------------------- |:-------------------------------------------- |
42+
| `@model` | [`DynamicPPL.@model`](@extref) | Define a probabilistic model |
43+
| `@varname` | [`AbstractPPL.@varname`](@extref) | Generate a `VarName` from a Julia expression |
44+
| `@submodel` | [`DynamicPPL.@submodel`](@extref) | Define a submodel |
45+
46+
### Inference
47+
48+
| Exported symbol | Documentation | Description |
49+
|:--------------- |:------------------------------------------------------------------------------------------------ |:------------------- |
50+
| `sample` | [`StatsBase.sample`](https://turinglang.org/AbstractMCMC.jl/stable/api/#Sampling-a-single-chain) | Sample from a model |
51+
52+
### Samplers
53+
54+
| Exported symbol | Documentation | Description |
55+
|:-------------------- |:--------------------------------------------- |:------------------------------------------------------------------- |
56+
| `Prior` | [`Turing.Inference.Prior`](@ref) | Sample from the prior distribution |
57+
| `MH` | [`Turing.Inference.MH`](@ref) | Metropolis–Hastings |
58+
| `Emcee` | [`Turing.Inference.Emcee`](@ref) | Affine-invariant ensemble sampler |
59+
| `ESS` | [`Turing.Inference.ESS`](@ref) | Elliptical slice sampling |
60+
| `Gibbs` | [`Turing.Inference.Gibbs`](@ref) | Gibbs sampling |
61+
| `GibbsConditional` | [`Turing.Inference.GibbsConditional`](@ref) | A "pseudo-sampler" to provide analytical conditionals to `Gibbs` |
62+
| `HMC` | [`Turing.Inference.HMC`](@ref) | Hamiltonian Monte Carlo |
63+
| `SGLD` | [`Turing.Inference.SGLD`](@ref) | Stochastic gradient Langevin dynamics |
64+
| `SGHMC` | [`Turing.Inference.SGHMC`](@ref) | Stochastic gradient Hamiltonian Monte Carlo |
65+
| `PolynomialStepsize` | [`Turing.Inference.PolynomialStepsize`](@ref) | Returns a function which generates polynomially decaying step sizes |
66+
| `HMCDA` | [`Turing.Inference.HMCDA`](@ref) | Hamiltonian Monte Carlo with dual averaging |
67+
| `NUTS` | [`Turing.Inference.NUTS`](@ref) | No-U-Turn Sampler |
68+
| `IS` | [`Turing.Inference.IS`](@ref) | Importance sampling |
69+
| `SMC` | [`Turing.Inference.SMC`](@ref) | Sequential Monte Carlo |
70+
| `PG` | [`Turing.Inference.PG`](@ref) | Particle Gibbs |
71+
| `CSMC` | [`Turing.Inference.CSMC`](@ref) | The same as PG |
72+
| `externalsampler` | [`Turing.Inference.externalsampler`](@ref) | Wrap an external sampler for use in Turing |
73+
74+
### Variational inference
75+
76+
See the [variational inference tutorial](https://turinglang.org/docs/tutorials/09-variational-inference/) for a walkthrough on how to use these.
77+
78+
| Exported symbol | Documentation | Description |
79+
|:--------------- |:---------------------------- |:--------------------------------------- |
80+
| `vi` | [`AdvancedVI.vi`](@extref) | Perform variational inference |
81+
| `ADVI` | [`AdvancedVI.ADVI`](@extref) | Construct an instance of a VI algorithm |
82+
83+
### Automatic differentiation types
84+
85+
These are used to specify the automatic differentiation backend to use.
86+
See the [AD guide](https://turinglang.org/docs/tutorials/docs-10-using-turing-autodiff/) for more information.
87+
88+
| Exported symbol | Documentation | Description |
89+
|:----------------- |:------------------------------------ |:----------------------------------------- |
90+
| `AutoForwardDiff` | [`ADTypes.AutoForwardDiff`](@extref) | ForwardDiff.jl backend |
91+
| `AutoReverseDiff` | [`ADTypes.AutoReverseDiff`](@extref) | ReverseDiff.jl backend |
92+
| `AutoZygote` | [`ADTypes.AutoZygote`](@extref) | Zygote.jl backend |
93+
| `AutoTracker` | [`ADTypes.AutoTracker`](@extref) | Tracker.jl backend |
94+
| `AutoTapir` | [`ADTypes.AutoTapir`](@extref) | Tapir.jl backend, only for ADTypes >= 1.0 |
95+
96+
### Debugging
97+
98+
```@docs
99+
setprogress!
100+
```
101+
102+
### Distributions
103+
104+
These distributions are defined in Turing.jl, but not in Distributions.jl.
105+
106+
```@docs
107+
Flat
108+
FlatPos
109+
BinomialLogit
110+
OrderedLogistic
111+
LogPoisson
112+
```
113+
114+
`BernoulliLogit` is part of Distributions.jl since version 0.25.77.
115+
If you are using an older version of Distributions where this isn't defined, Turing will export the same distribution.
116+
117+
```@docs
118+
Distributions.BernoulliLogit
119+
```
120+
121+
### Tools to work with distributions
122+
123+
| Exported symbol | Documentation | Description |
124+
|:--------------- |:-------------------------------------- |:-------------------------------------------------------------- |
125+
| `filldist` | [`DistributionsAD.filldist`](@extref) | Create a product distribution from a distribution and integers |
126+
| `arraydist` | [`DistributionsAD.arraydist`](@extref) | Create a product distribution from an array of distributions |
127+
| `NamedDist` | [`DynamicPPL.NamedDist`](@extref) | A distribution that carries the name of the variable |
128+
129+
### Predictions
130+
131+
```@docs
132+
predict
133+
```
134+
135+
### Querying model probabilities and quantities
136+
137+
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.
138+
139+
| Exported symbol | Documentation | Description |
140+
|:-------------------------- |:--------------------------------------------------------------------------------------------------------------------------------- |:--------------------------------------------------------------- |
141+
| `generated_quantities` | [`DynamicPPL.generated_quantities`](@extref) | Calculate additional quantities defined in a model |
142+
| `pointwise_loglikelihoods` | [`DynamicPPL.pointwise_loglikelihoods`](@extref) | Compute log likelihoods for each sample in a chain |
143+
| `logprior` | [`DynamicPPL.logprior`](@extref) | Compute log prior probability |
144+
| `logjoint` | [`DynamicPPL.logjoint`](@extref) | Compute log joint probability |
145+
| `LogDensityFunction` | [`DynamicPPL.LogDensityFunction`](@extref) | Wrap a Turing model to satisfy LogDensityFunctions.jl interface |
146+
| `condition` | [`AbstractPPL.condition`](@extref) | Condition a model on data |
147+
| `decondition` | [`AbstractPPL.decondition`](@extref) | Remove conditioning on data |
148+
| `conditioned` | [`DynamicPPL.conditioned`](@extref) | Return the conditioned values of a model |
149+
| `fix` | [`DynamicPPL.fix`](@extref) | Fix the value of a variable |
150+
| `unfix` | [`DynamicPPL.unfix`](@extref) | Unfix the value of a variable |
151+
| `OrderedDict` | [`OrderedCollections.OrderedDict`](https://juliacollections.github.io/OrderedCollections.jl/dev/ordered_containers/#OrderedDicts) | An ordered dictionary |
152+
153+
### Extra re-exports from Bijectors
154+
155+
Note that Bijectors itself does not export `ordered`.
156+
157+
```@docs
158+
Bijectors.ordered
159+
```
160+
161+
### Point estimates
162+
163+
See the [mode estimation tutorial](https://turinglang.org/docs/tutorials/docs-17-mode-estimation/) for more information.
164+
165+
| Exported symbol | Documentation | Description |
166+
|:---------------------- |:-------------------------------------------------- |:-------------------------------------------- |
167+
| `maximum_a_posteriori` | [`Turing.Optimisation.maximum_a_posteriori`](@ref) | Find a MAP estimate for a model |
168+
| `maximum_likelihood` | [`Turing.Optimisation.maximum_likelihood`](@ref) | Find a MLE estimate for a model |
169+
| `MAP` | [`Turing.Optimisation.MAP`](@ref) | Type to use with Optim.jl for MAP estimation |
170+
| `MLE` | [`Turing.Optimisation.MLE`](@ref) | Type to use with Optim.jl for MLE estimation |

‎docs/src/api/Inference.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# API: `Turing.Inference`
2+
3+
```@autodocs
4+
Modules = [Turing.Inference]
5+
Order = [:type, :function]
6+
```

‎docs/src/api/Optimisation.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# API: `Turing.Optimisation`
2+
3+
```@autodocs
4+
Modules = [Turing.Optimisation]
5+
Order = [:type, :function]
6+
```

‎docs/src/index.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Turing.jl
2+
3+
This site contains the API documentation for the identifiers exported by Turing.jl.
4+
5+
If you are looking for usage examples and guides, please visit [https://turinglang.org/docs](https://turinglang.org/docs).

‎docs/src/library/advancedhmc.md

Lines changed: 0 additions & 25 deletions
This file was deleted.

0 commit comments

Comments
 (0)