Skip to content

Commit 95c797f

Browse files
limartalimarta
authored
Documentation Refactoring (#526)
* Documentation revision start * Doc changes * swap in * HMM example * Serialization as an extension * Edit docs. Add attribution * API listings * Reformat code blocks * Delete docs/out.txt * Remove files * Add instrutions * Remove tutorial * Directory changes * Fix gfi explanation code snippets. Other page fixes * How-to section * More how-tos * Ported SML tutorial. More directory refactoring * Fix how to titles. Add MCMC description in API * Added more undocumented fucntions. Edited docstrings. Minor config changes
1 parent 90c6a5d commit 95c797f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+4748
-676
lines changed

‎Project.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,4 @@ julia = "1.6"
3434
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
3535

3636
[targets]
37-
test = ["Test"]
37+
test = ["Test"]

‎docs/.gitignore

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/Project.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
[deps]
22
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
33
Gen = "ea4f424c-a589-11e8-07c0-fd5c91b9da4a"
4+
Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
45

56
[compat]
6-
Documenter = "0.27"
7+
Documenter = "1"

‎docs/README.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Website Docs
2+
- `pages.jl` to find skeleton of website.
3+
- `make.jl` to build the website index.
4+
5+
The docs are divided in roughly four sections:
6+
- Getting Started + Tutorials
7+
- How-to Guides
8+
- API = Modeling API + Inference API
9+
- Explanations + Internals
10+
11+
12+
# Developing
13+
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`.
14+
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.
15+
16+
Code snippets must use the triple backtick with a label to run. The environment carries over so long as the labels match. Example:
17+
18+
```@example tutorial_1
19+
x = rand()
20+
```
21+
22+
```@example tutorial_1
23+
print(x)
24+
```

‎docs/build_docs_locally.sh

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

‎docs/make.jl

Lines changed: 13 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,20 @@
1+
# Run: julia --project make.jl
12
using Documenter, Gen
23

4+
include("pages.jl")
35
makedocs(
4-
sitename = "Gen",
56
modules = [Gen],
6-
pages = [
7-
"Home" => "index.md",
8-
"Getting Started" => "getting_started.md",
9-
"Tutorials" => "tutorials.md",
10-
"Modeling Languages and APIs" => [
11-
"Generative Functions" => "ref/gfi.md",
12-
"Probability Distributions" => "ref/distributions.md",
13-
"Built-in Modeling Language" => "ref/modeling.md",
14-
"Generative Function Combinators" => "ref/combinators.md",
15-
"Choice Maps" => "ref/choice_maps.md",
16-
"Selections" => "ref/selections.md",
17-
"Optimizing Trainable Parameters" => "ref/parameter_optimization.md",
18-
"Trace Translators" => "ref/trace_translators.md",
19-
"Extending Gen" => "ref/extending.md"
20-
],
21-
"Standard Inference Library" => [
22-
"Importance Sampling" => "ref/importance.md",
23-
"MAP Optimization" => "ref/map.md",
24-
"Markov chain Monte Carlo" => "ref/mcmc.md",
25-
"MAP Optimization" => "ref/map.md",
26-
"Particle Filtering" => "ref/pf.md",
27-
"Variational Inference" => "ref/vi.md",
28-
"Learning Generative Functions" => "ref/learning.md"
29-
],
30-
"Internals" => [
31-
"Optimizing Trainable Parameters" => "ref/internals/parameter_optimization.md",
32-
"Modeling Language Implementation" => "ref/internals/language_implementation.md"
33-
]
34-
]
7+
doctest = false,
8+
clean = true,
9+
warnonly = true,
10+
format = Documenter.HTML(;
11+
assets = String["assets/header.js", "assets/header.css", "assets/theme.css"],
12+
collapselevel=1,
13+
),
14+
sitename = "Gen.jl",
15+
pages = pages,
16+
checkdocs=:exports,
17+
pagesonly=true,
3518
)
3619

3720
deploydocs(

‎docs/pages.jl

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
pages = [
2+
"Home" => "index.md",
3+
"Getting Started" => [
4+
"Example 1: Linear Regression" => "getting_started/linear_regression.md",
5+
],
6+
"Tutorials" => [
7+
"Basics" => [
8+
"tutorials/basics/modeling_in_gen.md",
9+
"tutorials/basics/gfi.md",
10+
"tutorials/basics/combinators.md",
11+
"tutorials/basics/particle_filter.md",
12+
"tutorials/basics/vi.md",
13+
],
14+
"Advanced" => [
15+
"tutorials/trace_translators.md",
16+
],
17+
"Model Optmizations" => [
18+
"Speeding Inference with the Static Modeling Language" => "tutorials/model_optimizations/scaling_with_sml.md",
19+
],
20+
],
21+
"How-to Guides" => [
22+
"MCMC Kernels" => "how_to/mcmc_kernels.md",
23+
"Custom Distributions" => "how_to/custom_distributions.md",
24+
"Custom Modeling Languages" => "how_to/custom_dsl.md",
25+
"Custom Gradients" => "how_to/custom_derivatives.md",
26+
"Incremental Computation" => "how_to/custom_incremental_computation.md",
27+
],
28+
"API Reference" => [
29+
"Modeling Library" => [
30+
"Generative Functions" => "api/model/gfi.md",
31+
"Probability Distributions" => "api/model/distributions.md",
32+
"Choice Maps" => "api/model/choice_maps.md",
33+
"Built-in Modeling Languages" => "api/model/modeling.md",
34+
"Combinators" => "api/model/combinators.md",
35+
"Selections" => "api/model/selections.md",
36+
"Optimizing Trainable Parameters" => "api/model/parameter_optimization.md",
37+
"Trace Translators" => "api/model/trace_translators.md",
38+
],
39+
"Inference Library" => [
40+
"Importance Sampling" => "api/inference/importance.md",
41+
"MAP Optimization" => "api/inference/map.md",
42+
"Markov chain Monte Carlo" => "api/inference/mcmc.md",
43+
"MAP Optimization" => "api/inference/map.md",
44+
"Particle Filtering" => "api/inference/pf.md",
45+
"Variational Inference" => "api/inference/vi.md",
46+
"Learning Generative Functions" => "api/inference/learning.md"
47+
],
48+
],
49+
"Explanation and Internals" => [
50+
"Modeling Language Implementation" => "explanations/language_implementation.md",
51+
"explanations/combinator_design.md"
52+
]
53+
]

‎docs/src/ref/importance.md renamed to ‎docs/src/api/inference/importance.md

File renamed without changes.

‎docs/src/ref/learning.md renamed to ‎docs/src/api/inference/learning.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ Then, the traces of the model can be obtained by simulating from the variational
209209
Instead of fitting the variational approximation from scratch for each observation, it is possible to fit an *inference model* instead, that takes as input the observation, and generates a distribution on latent variables as output (as in the wake sleep algorithm).
210210
When we train the variational approximation by minimizing the evidence lower bound (ELBO) this is called amortized variational inference.
211211
Variational autencoders are an example.
212-
It is possible to perform amortized variational inference using [`black_box_vi`](@ref) or [`black_box_vimco!`](@ref).
212+
It is possible to perform amortized variational inference using [`black_box_vi!`](@ref) or [`black_box_vimco!`](@ref).
213213

214214
## References
215215

‎docs/src/ref/map.md renamed to ‎docs/src/api/inference/map.md

File renamed without changes.

‎docs/src/api/inference/mcmc.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Markov chain Monte Carlo (MCMC)
2+
3+
Gen supports standard Markov Chain Monte Carlo algorithms and allows users to write their own custom kernels.
4+
```@index
5+
Pages = ["mcmc.md"]
6+
```
7+
8+
```@docs
9+
metropolis_hastings
10+
mh
11+
mala
12+
hmc
13+
elliptical_slice
14+
@pkern
15+
@kern
16+
@rkern
17+
reversal
18+
involutive_mcmc
19+
```

‎docs/src/ref/pf.md renamed to ‎docs/src/api/inference/pf.md

File renamed without changes.

‎docs/src/api/inference/vi.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## Variational inference
2+
There are two procedures in the inference library for performing black box variational inference.
3+
Each of these procedures can also train the model using stochastic gradient descent, as in a variational autoencoder.
4+
```@docs
5+
black_box_vi!
6+
black_box_vimco!
7+
```

‎docs/src/ref/choice_maps.md renamed to ‎docs/src/api/model/choice_maps.md

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,13 @@ Choice maps also implement:
3030
- `==`, which tests if two choice maps have the same addresses and values at those addresses.
3131

3232

33-
## Mutable Choice Maps
33+
34+
```@docs
35+
DynamicChoiceMap
36+
EmptyChoiceMap
37+
StaticChoiceMap
38+
choicemap
39+
```
3440

3541
A mutable choice map can be constructed with [`choicemap`](@ref), and then populated:
3642
```julia
@@ -45,8 +51,18 @@ There is also a constructor that takes initial (address, value) pairs:
4551
choices = choicemap((:x, true), ("foo", 1.25), (:y => 1 => :z, -6.3))
4652
```
4753

54+
4855
```@docs
49-
choicemap
5056
set_value!
5157
set_submap!
58+
Base.merge(::ChoiceMap, ::ChoiceMap)
59+
Base.merge(::ChoiceMap, ::Vararg{ChoiceMap})
60+
Base.isempty(::ChoiceMap)
5261
```
62+
63+
```@docs
64+
Gen.pair
65+
Gen.unpair
66+
Gen.ChoiceMapNestedView
67+
```
68+

‎docs/src/ref/combinators.md renamed to ‎docs/src/api/model/combinators.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,9 @@ FunctionalCollections.PersistentVector{Any}[true, false, true, false, true]
112112

113113
## Recurse combinator
114114

115-
TODO: document me
115+
```@docs
116+
Recurse
117+
```
116118

117119
```@raw html
118120
<div style="text-align:center">
@@ -161,3 +163,4 @@ The resulting trace contains the subtrace from the branch with index `2` - in th
161163
│
162164
└── :z : 13.552870875213735
163165
```
166+

‎docs/src/ref/distributions.md renamed to ‎docs/src/api/model/distributions.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,11 @@
1-
# Probability Distributions
1+
# [Probability Distributions](@id distributions)
2+
3+
```@docs
4+
random
5+
logpdf
6+
has_output_grad
7+
logpdf_grad
8+
```
29

310
Gen provides a library of built-in probability distributions, and four ways of
411
defining custom distributions, each of which are explained below:
@@ -39,6 +46,7 @@ piecewise_uniform
3946
poisson
4047
uniform
4148
uniform_discrete
49+
broadcasted_normal
4250
```
4351

4452
## [Defining New Distributions Inline with the `@dist` DSL](@id dist_dsl)

‎docs/src/api/model/gfi.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
## [Generative Functions](@id gfi_api)
2+
3+
```@docs
4+
GenerativeFunction
5+
Trace
6+
```
7+
8+
The complete set of methods in the generative function interface (GFI) is:
9+
10+
```@docs
11+
simulate
12+
generate
13+
update
14+
regenerate
15+
get_args
16+
get_retval
17+
get_choices
18+
get_score
19+
get_gen_fn
20+
Base.getindex
21+
project
22+
propose
23+
assess
24+
has_argument_grads
25+
has_submap
26+
accepts_output_grad
27+
accumulate_param_gradients!
28+
choice_gradients
29+
get_params
30+
```
31+
32+
```@docs
33+
Diff
34+
NoChange
35+
UnknownChange
36+
SetDiff
37+
Diffed
38+
```
39+
40+
```@docs
41+
CustomUpdateGF
42+
apply_with_state
43+
update_with_state
44+
```
45+
46+
```@docs
47+
CustomGradientGF
48+
apply
49+
gradient
50+
```
51+
52+
```@docs
53+
Gen.init_update_state
54+
Gen.apply_update!
55+
```

0 commit comments

Comments
 (0)