Merge pull request #543 from probcomp/reorganize_docs

Reorganize and add documentation

.github/workflows/ContinuousIntegration.yml

@@ -6,8 +6,18 @@ name: ContinuousIntegration
 on:
   push:
     branches: [ master ]
+    paths-ignore:
+      - 'docs/**'
+      - 'README.md'
+      - 'CONTRIBUTING.md'
+      - 'WEBSITE.md'
   pull_request:
     branches: [ master ]
+    paths-ignore:
+      - 'docs/**'
+      - 'README.md'
+      - 'CONTRIBUTING.md'
+      - 'WEBSITE.md'
 
 jobs:
   ContinuousIntegration:

.github/workflows/DocPreviewCleanup.yml

@@ -0,0 +1,36 @@
+# Adapted from
+# https://documenter.juliadocs.org/stable/man/hosting/#Cleaning-up-gh-pages
+
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: docs/previews/PR${{ github.event.number }}

CONTRIBUTING.md

@@ -34,7 +34,6 @@
 
 - In the introduction section(s), provide at least a few sentences of high-level description of the feature, to orient the user. Include external links and internal links. Then, include some short code snippets showing a minimal example of the feature being used. If relevant, include some simple Tex math.
 
-- Build the docs locally to test that it builds and looks right:
-```sh
-./docs/build_docs_locally.sh
-```
+- Build the docs locally to test that it builds and looks right.
+
+- Once you have a made a PR and are assigned a PR `NUMBER`, update your PR description with a link to the automatically generated documentation preview at https://www.gen.dev/docs/previews/PR{NUMBER}.

WEBSITE.md

@@ -1,21 +1,24 @@
-The Gen website is hosted on Github pages at https://probcomp.github.io/Gen/
+The Gen website is hosted at https://www.gen.dev/.
 
 The website is generated from the source files that are at the head commit of the `gh-pages` branch of the Gen repository.
 
 To edit the website, check out the `gh-pages` branch, and commit and push changes.
 
-Automatically-generated Gen documentation is pushed to the `gh-pages` branch whenever a commit is made to the `master` branch of the Gen repository using a combination of Github Actions and Documenter.jl, which are configured in the files `.github/workflows/Documentation.yml` and `docs/make.jl` in the `master` branch.
+Automatically-generated Gen documentation is pushed to the `docs` folder of the `gh-pages` branch whenever a commit is made to the `master` branch of the Gen repository using a combination of Github Actions and Documenter.jl, which are configured in the files `.github/workflows/Documentation.yml` and `docs/make.jl` in the `master` branch. When a pull request is merged into the `master` branch, the `gh-pages` branch is updated with the new documentation, and documentation previews will be cleaned up by the `.github/workflows/Documentation.yml` workflow.
+
 The automatically-managed files and directories are:
 
-- `dev/` (documentation for the version of Gen on the head of `master` branch)
+- `docs/dev/` (documentation for the version of Gen on the head of `master` branch)
+
+- `docs/v*.*.*/` (directories that contain documentation for each tagged release of Gen)
 
-- `v*.*.*/` (directories that contain documentation for each tagged release of Gen)
+- `docs/latest/` (a symbolic link to `dev/`)
 
-- `latest/` (a symbolic link to `dev/`)
+- `docs/stable/` (a symbolic link to the documentation directory of the latest tagged release Gen)
 
-- `stable/` (a symbolic link to the documentation directory of the latest tagged release Gen)
+- `docs/previews/` (documentation previews for unmerged pull requests)
 
-- `versions.js`
+- `docs/versions.js`
 
 *Do not make commits that modify the contents of these automatically managed files and directories.*
 

docs/README.md

@@ -1,17 +1,18 @@
-# Website Docs
-- `pages.jl` to find skeleton of website.
-- `make.jl` to build the website index.
+# Gen.jl Documentation
 
-The docs are divided in roughly four sections:
+- `pages.jl` to find skeleton of the Gen.jl documentation.
+- `make.jl` to build the documentation website index.
+
+The documentation is divided into three sections:
 - Getting Started + Tutorials
 - How-to Guides
-- API = Modeling API + Inference API
-- Explanations + Internals
-
+- Reference Guides
 
 # Developing
-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`.
-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.
+
+To build the docs, run `julia --make.jl`. Alternatively, start the Julia REPL, activate the `Project.toml` in this directory, then include `make.jl`. For debugging, consider setting `draft=true` in the `makedocs` function found in `make.jl`. This will avoid running the `@example` blocks when generating the tutorials.
+
+Currently you must write the tutorial directly in the docs rather than in a source file. See `tutorials` for examples.
 
 Code snippets must use the triple backtick with a label to run. The environment carries over so long as the labels match. Example:
 
@@ -21,4 +22,4 @@ x = rand()
 
 ```@example tutorial_1
 print(x)
-```
+```

docs/make.jl

@@ -8,7 +8,6 @@ makedocs(
     clean = true,
     warnonly = true,
     format = Documenter.HTML(;
-        assets = String["assets/header.js", "assets/header.css", "assets/theme.css"],
         collapselevel=1,
     ),
     sitename = "Gen.jl",
@@ -21,4 +20,5 @@ deploydocs(
     repo = "github.com/probcomp/Gen.jl.git",
     target = "build",
     dirname = "docs",
+    push_preview = true,
 )

docs/pages.jl

@@ -1,53 +1,46 @@
 pages = [
-    "Home" => "index.md",
-    "Getting Started" => [
-        "Example 1: Linear Regression" => "getting_started/linear_regression.md",
-    ],
+    "Gen.jl" => "index.md",
     "Tutorials" => [
-        "Basics" => [
-            "tutorials/basics/modeling_in_gen.md",
-            "tutorials/basics/gfi.md",
-            "tutorials/basics/combinators.md",
-            "tutorials/basics/particle_filter.md",
-            "tutorials/basics/vi.md",
-        ],
-        "Advanced" => [
-            "tutorials/trace_translators.md",
-        ],
-        "Model Optmizations" => [
-            "Speeding Inference with the Static Modeling Language" => "tutorials/model_optimizations/scaling_with_sml.md",
-        ],
+        "Getting Started" => "tutorials/getting_started.md",
+        "Introduction to Modeling in Gen" => "tutorials/modeling_in_gen.md",
+        "Object Tracking with SMC" => "tutorials/smc.md",
+        "Variational Inference in Gen" => "tutorials/vi.md",
+        "Learning Generative Functions" => "tutorials/learning_gen_fns.md",
+        "Speeding Up Inference with the SML" => "tutorials/scaling_with_sml.md",
     ],
     "How-to Guides" => [
-        "MCMC Kernels" => "how_to/mcmc_kernels.md",
-        "Custom Distributions" => "how_to/custom_distributions.md",
-        "Custom Modeling Languages" => "how_to/custom_dsl.md",
-        "Custom Gradients" => "how_to/custom_derivatives.md",
-        "Incremental Computation" => "how_to/custom_incremental_computation.md",
+        "Extending Gen" => "how_to/extending_gen.md",
+        "Adding New Distributions" => "how_to/custom_distributions.md",
+        "Adding New Generative Functions" => "how_to/custom_gen_fns.md",
+        "Custom Gradients" => "how_to/custom_gradients.md",
+        "Custom Incremental Computation" => "how_to/custom_incremental_computation.md",
     ],
-    "API Reference" => [
+    "Reference" => [
+        "Core Interfaces" => [
+            "Generative Function Interface" => "ref/core/gfi.md",
+            "Choice Maps" => "ref/core/choice_maps.md",
+            "Selections" => "ref/core/selections.md",
+            "Change Hints" => "ref/core/change_hints.md",
+        ],
         "Modeling Library" => [
-            "Generative Functions" => "api/model/gfi.md",
-            "Probability Distributions" => "api/model/distributions.md",
-            "Choice Maps" => "api/model/choice_maps.md",
-            "Built-in Modeling Languages" => "api/model/modeling.md",
-            "Combinators" => "api/model/combinators.md",
-            "Selections" => "api/model/selections.md",
-            "Optimizing Trainable Parameters" => "api/model/parameter_optimization.md",
-            "Trace Translators" => "api/model/trace_translators.md",
+            "Built-In Modeling Language" => "ref/modeling/dml.md",
+            "Static Modeling Language" => "ref/modeling/sml.md",
+            "Probability Distributions" => "ref/modeling/distributions.md",
+            "Combinators" => "ref/modeling/combinators.md",
+            "Custom Generative Functions" => "ref/modeling/custom_gen_fns.md",
         ],
         "Inference Library" => [
-            "Importance Sampling" => "api/inference/importance.md",
-            "MAP Optimization" => "api/inference/map.md",
-            "Markov chain Monte Carlo" => "api/inference/mcmc.md",
-            "MAP Optimization" => "api/inference/map.md",
-            "Particle Filtering" => "api/inference/pf.md",
-            "Variational Inference" => "api/inference/vi.md",
-            "Learning Generative Functions" => "api/inference/learning.md"
+            "Importance Sampling" => "ref/inference/importance.md",
+            "Markov Chain Monte Carlo" => "ref/inference/mcmc.md",
+            "Particle Filtering & SMC" => "ref/inference/pf.md",
+            "Trace Translators" => "ref/inference/trace_translators.md",
+            "Parameter Optimization" => "ref/inference/parameter_optimization.md",
+            "MAP Optimization" => "ref/inference/map.md",
+            "Variational Inference" => "ref/inference/vi.md",
+            "Wake-Sleep Learning" => "ref/inference/wake_sleep.md",
         ],
+        "Internals" => [
+            "Modeling Language Implementation" => "ref/internals/language_implementation.md",
+        ]
     ],
-    "Explanation and Internals" => [
-        "Modeling Language Implementation" => "explanations/language_implementation.md",
-        "explanations/combinator_design.md"
-    ]
 ]