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.

0 commit comments

Comments
 (0)