Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,5 @@ venv
site_libs
.DS_Store
index_files
digest.txt
digest.txt
*.bak
101 changes: 50 additions & 51 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,106 +1,105 @@
# Turing.jl Documentation and Tutorials

**https://turinglang.org/docs/**
**https://turinglang.org/docs/**

## Contributing
## Contributing

The easiest way to contribute to the documentation is to simply open a pull request.
A preview version of the documentation is built for PRs, so you can see how your changes look without having to build the entire site locally.
(Note that if you are editing a tutorial that takes a long time to run, this feedback may take a while.)
The easiest way to contribute to the documentation is to simply open a pull request.
A preview version of the documentation is built for pull requests, so you can see how your changes look without having to build the entire site locally.
(Note that if you are editing a tutorial that takes a long time to run, this feedback may take a while.)

The `main` branch contains the Quarto source code.
The HTML documentation is automatically built using GitHub Actions, and deployed to the `gh-pages` branch, so you do not have to build and commit the HTML files yourself.
The `main` branch contains the Quarto source code.
The HTML documentation is automatically built using GitHub Actions, and deployed to the `gh-pages` branch, so you do not have to build and commit the HTML files yourself.

## Local development
## Local development

If you wish to render the docs website locally, you'll need to have [Quarto](https://quarto.org/docs/download/) installed (at least version 1.6.31) on your computer.
Then:
If you wish to render the docs website locally, you'll need to have [Quarto](https://quarto.org/docs/download/) installed (at least version 1.6.31) on your computer.
Then:

1. Clone this repository:
1. Clone this repository:

```bash
git clone https://github.com/TuringLang/docs
```
```

2. Navigate into the cloned directory:
2. Navigate into the cloned directory:

```bash
cd docs
```
```

3. Instantiate the project environment:
3. Instantiate the project environment:

```bash
julia --project=. -e 'using Pkg; Pkg.instantiate()'
```
```

4. Preview the website using Quarto.
4. Preview the website using Quarto.

> [!WARNING]
> This will take a _very_ long time, as it will build every tutorial from scratch. See [below](#faster-rendering) for ways to speed this up.
> [!WARNING]
> This will take a _very_ long time, as it will build every tutorial from scratch. See [below](#faster-rendering) for ways to speed this up.

```bash
quarto preview
```
```

This will launch a local server at http://localhost:4200/, which you can view in your web browser by navigating to the link shown in your terminal.
This will launch a local server at http://localhost:4200/, which you can view in your web browser by navigating to the link shown in your terminal.

5. Render the website locally:
5. Render the website locally:

```bash
quarto render
```
```

This will build the entire documentation and place the output in the `_site` folder.
You can then view the rendered website by launching a HTTP server from that directory, e.g. using Python:
This will build the entire documentation and place the output in the `_site` folder.
You can then view the rendered website by launching an HTTP server from that directory, e.g. using Python:

```bash
cd _site
python -m http.server 8000
```
```

Then, navigate to http://localhost:8000/ in your web browser.
Then, navigate to http://localhost:8000/ in your web browser.

## Faster rendering
## Faster rendering

Note that rendering the entire documentation site can take a long time (usually multiple hours).
If you wish to speed up local rendering, there are two options available:
Note that rendering the entire documentation site can take a long time (usually multiple hours).
If you wish to speed up local rendering, there are two options available:

1. Render a single tutorial or `qmd` file without compiling the entire site.
To do this, pass the `qmd` file as an argument to `quarto render`:
1. Render a single tutorial or `qmd` file without compiling the entire site.
To do this, pass the `qmd` file as an argument to `quarto render`:

```
quarto render path/to/index.qmd
```

(Note that `quarto preview` does not support this single-file rendering.)
```
(Note that `quarto preview` does not support this single-file rendering.)

2. Download the most recent `_freeze` folder from the [GitHub releases of this repo](https://github.com/turinglang/docs/releases), and place it in the root of the project.
The `_freeze` folder stores the cached outputs from a previous build of the documentation.
If it is present, Quarto will reuse the outputs of previous computations for any files for which the source is unchanged.
2. Download the most recent `_freeze` folder from the [GitHub releases of this repo](https://github.com/turinglang/docs/releases), and place it in the root of the project.
The `_freeze` folder stores the cached outputs from a previous build of the documentation.
If it is present, Quarto will reuse the outputs of previous computations for any files for which the source is unchanged.

Note that the validity of a `_freeze` folder depends on the Julia environment that it was created with, because different package versions may lead to different outputs.
In the GitHub release, the `Manifest.toml` is also provided, and you should also download this and place it in the root directory of the docs.
Note that the validity of a `_freeze` folder depends on the Julia environment that it was created with, because different package versions may lead to different outputs.
In the GitHub release, the `Manifest.toml` is also provided, and you should also download this and place it in the root directory of the docs.

If there isn't a suitably up-to-date `_freeze` folder in the releases, you can generate a new one by [triggering a run for the `create_release.yml` workflow](https://github.com/TuringLang/docs/actions/workflows/create_release.yml).
(You will need to have the appropriate permissions; please create an issue if you need help with this.)
If there isn't a suitably up-to-date `_freeze` folder in the releases, you can generate a new one by [triggering a run for the `create_release.yml` workflow](https://github.com/TuringLang/docs/actions/workflows/create_release.yml) (You will need to have the appropriate permissions; please create an issue if you need help with this).

## Troubleshooting build issues
## Troubleshooting build issues

As described in the [Quarto docs](https://quarto.org/docs/computations/julia.html#using-the-julia-engine), Quarto's Julia engine uses a worker process behind the scenes.
Sometimes this can result in issues with old package code not being unloaded (e.g. when package versions are upgraded).
If you find that Quarto's execution is failing with errors that aren't reproducible via a normal REPL, try adding the `--execute-daemon-restart` flag to the `quarto render` command:
As described in the [Quarto docs](https://quarto.org/docs/computations/julia.html#using-the-julia-engine), Quarto's Julia engine uses a worker process behind the scenes.
Sometimes this can result in issues with old package code not being unloaded (e.g. when package versions are upgraded).
If you find that Quarto's execution is failing with errors that aren't reproducible via a normal REPL, try adding the `--execute-daemon-restart` flag to the `quarto render` command:

```bash
quarto render /path/to/index.qmd --execute-daemon-restart
```
```

And also, kill any stray Quarto processes that are still running (sometimes it keeps running in the background):
And also, kill any stray Quarto processes that are still running (sometimes it keeps running in the background):

```bash
pkill -9 -f quarto
```
```

## License
## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
This project is licensed under the MIT License - see the [License](License) file for details.
2 changes: 1 addition & 1 deletion _quarto.yml
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ format:

</div>
<div class="footer-bottom">
<p>Turing.jl was created by <a href="https://mlg.eng.cam.ac.uk/hong/" target="_blank" rel="noopener">Hong Ge</a>, and maintained by the core <a href="https://turinglang.org/team/" target="_blank" rel="noopener">team</a> of developers and <a href="https://github.com/TuringLang/Turing.jl/graphs/contributors" target="_blank" rel="noopener">contributors</a>.<br>© 2025 The Turing Project Contributors. <a href="https://github.com/TuringLang/Turing.jl/blob/master/LICENCE" target="_blank" rel="noopener">MIT License</a>.</p>
<p>Turing.jl was created by <a href="https://mlg.eng.cam.ac.uk/hong/" target="_blank" rel="noopener">Hong Ge</a>, and maintained by the core <a href="https://turinglang.org/team/" target="_blank" rel="noopener">team</a> of developers and <a href="https://github.com/TuringLang/Turing.jl/graphs/contributors" target="_blank" rel="noopener">contributors</a>.<br>© 2025 The Turing Project Contributors. <a href="https://github.com/TuringLang/Turing.jl/blob/master/LICENSE" target="_blank" rel="noopener">MIT License</a>.</p>
<a href="https://github.com/TuringLang/docs/" target="_blank" rel="noopener" class="footer-source-link"><i class="bi bi-github"></i> Website Source</a>
</div>
</div>
Expand Down
12 changes: 6 additions & 6 deletions core-functionality/index.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@ using Turing
# Add four processes to use for sampling.
addprocs(4; exeflags="--project=$(Base.active_project())")

# Initialize everything on all the processes.
# Initialise everything on all the processes.
# Note: Make sure to do this after you've already loaded Turing,
# so each process does not have to precompile.
# Parallel sampling may fail silently if you do not do this.
Expand Down Expand Up @@ -329,7 +329,7 @@ Inputs to the model that have a value `missing` are treated as parameters, aka r
```{julia}
@model function gdemo(x, ::Type{T}=Float64) where {T}
if x === missing
# Initialize `x` if missing
# Initialise `x` if missing
x = Vector{T}(undef, 2)
end
s² ~ InverseGamma(2, 3)
Expand All @@ -344,7 +344,7 @@ model = gdemo(missing)
c = sample(model, HMC(0.05, 20), 500)
```

Note the need to initialize `x` when missing since we are iterating over its elements later in the model.
Note the need to initialise `x` when missing since we are iterating over its elements later in the model.
The generated values for `x` can be extracted from the `Chains` object using `c[:x]`.

Turing also supports mixed `missing` and non-`missing` values in `x`, where the missing ones will be treated as random variables to be sampled while the others get treated as observations.
Expand Down Expand Up @@ -376,7 +376,7 @@ using Turing

@model function generative(x=missing, ::Type{T}=Float64) where {T<:Real}
if x === missing
# Initialize x when missing
# Initialise x when missing
x = Vector{T}(undef, 10)
end
s² ~ InverseGamma(2, 3)
Expand Down Expand Up @@ -597,10 +597,10 @@ logging is enabled as default but might slow down inference. It can be turned on
or off by setting the keyword argument `progress` of `sample` to `true` or `false`.
Moreover, you can enable or disable progress logging globally by calling `setprogress!(true)` or `setprogress!(false)`, respectively.

Turing uses heuristics to select an appropriate visualization backend. If you
Turing uses heuristics to select an appropriate visualisation backend. If you
use Jupyter notebooks, the default backend is
[ConsoleProgressMonitor.jl](https://github.com/tkf/ConsoleProgressMonitor.jl).
In all other cases, progress logs are displayed with
[TerminalLoggers.jl](https://github.com/c42f/TerminalLoggers.jl). Alternatively,
if you provide a custom visualization backend, Turing uses it instead of the
if you provide a custom visualisation backend, Turing uses it instead of the
default backend.
Loading
Loading