|
| 1 | +--- |
| 2 | +title: Documentation |
| 3 | +--- |
| 4 | + |
| 5 | +# Navigating Turing's documentation system |
| 6 | + |
| 7 | +Each of the packages in the Turing ecosystem (see [Libraries](/library)) has its own documentation, which is typically found in the `docs` folder of the corresponding package. |
| 8 | +For example, the source code for DynamicPPL's documentation can be found in [its repository](https://github.com/TuringLang/DynamicPPL.jl). |
| 9 | + |
| 10 | +On top of the library-specific documentation, we also have a general documentation repository, which is what builds the website you are currently reading! |
| 11 | +Anything that appears in `turinglang.org/docs` is built from the [`docs` repository](https://github.com/TuringLang/docs). |
| 12 | + |
| 13 | +Other sections of the website (anything that isn't a package, or a tutorial) – for example, the list of libraries – is built from the [`turinglang.github.io` repository](https://github.com/TuringLang/turinglang.github.io). |
| 14 | + |
| 15 | +*In general, we prefer documentation for Turing users to be written on the `docs` repository.* |
| 16 | +This is because it is more easily discoverable for users via the search bar and sidebar. |
| 17 | + |
| 18 | +Documentation written on the individual package repositories can be found via the main site's search bar (due to a GitHub workflow that scrapes all the packages' contents and indexes them here), but once you navigate to a package's documentation, you cannot then use the sidebar to come back to the main documentation site. |
| 19 | +As such, we tend to only use package-specific documentation for developer notes and API docs. |
| 20 | + |
| 21 | +## Documenting unreleased features |
| 22 | + |
| 23 | +There are sometimes cases where it is not possible to add docs to the `docs` repository. |
| 24 | +In particular, because the `docs` repo builds from a released version of Turing and all its dependencies, new features in unreleased versions cannot be documented here. |
| 25 | +However, it's always better to document things as you go along rather than to wait for a release and then play catch-up! |
| 26 | + |
| 27 | +In such instances, we recommend first adding documentation to the relevant package's internal documentation (using Documenter.jl as usual), and later copying it over to the main `docs` repository (adjusting for the Quarto format) once the new version is released. |
| 28 | +Note that because the `docs` repository is tied to a specific version of Turing.jl, if you have updated the documentation for a new dependency of Turing (e.g. DynamicPPL or Bijectors), you also need to ensure that there is a version of Turing.jl that is compatible with that new version. |
| 29 | + |
| 30 | +# How to contribute to the docs repo |
| 31 | + |
| 32 | +## Local development |
| 33 | + |
| 34 | +The `TuringLang/docs` repository uses Quarto. |
| 35 | +You can add a new page by creating a new `.qmd` file and including its filepath in the top-level `_quarto.yml` file, which defines the structure of the website. |
| 36 | +Generally, we prefer adding individual `index.qmd` files in new folders, as this leads to cleaner URLs. |
| 37 | + |
| 38 | +When you create a new page, you can test it locally by running `quarto render /path/to/mynewpage/index.qmd`, and then launching a HTTP server from the folder containing the rendered HTML file (for example, using `cd _site/path/to/mynewpage && python -m http.server`). |
| 39 | + |
| 40 | +Note that if you use `quarto preview`, this may take a very long time since Quarto will attempt to render the entire site! |
| 41 | +You can see the [repository README](https://github.com/TuringLang/docs) for some information on how to get around this using the `_freeze` folder. |
| 42 | + |
| 43 | +## The docs environment |
| 44 | + |
| 45 | +The `docs` repository is built from a single Manifest file, which contains a pinned version of Turing.jl. |
| 46 | +All notebooks are run with the same environment, which ensures consistency across the documentation site. |
| 47 | + |
| 48 | +In general, you should **not** add new packages to this environment which **depend** on Turing (i.e., reverse dependencies of Turing), or packages that have Turing extensions. |
| 49 | +The reason for this is because such packages will have compatibility bounds on Turing. |
| 50 | +Thus, we will be unable to update the docs to use the newest Turing version, until and unless those packages also update their compatibility bounds. |
| 51 | + |
| 52 | +Whenever a new version of Turing.jl is released, the Manifest file should ideally be updated (with a single `] up` in the Julia REPL), and the new docs published. |
| 53 | +This process is not yet automated, though, so sometimes the version of Turing may fall behind the latest release. |
| 54 | +Usually for minor versions we make sure to update the docs as soon as practicable, but less so for patch versions. |
| 55 | + |
| 56 | +## GitHub CI |
| 57 | + |
| 58 | +Each PR to the `docs` repository will trigger two GitHub Actions workflows: |
| 59 | + |
| 60 | +1. The workflow that builds the documentation. If this workflow fails, it's usually due to an error in the code, or some environment resolution issues. |
| 61 | + |
| 62 | + :::{.callout-tip} |
| 63 | + If you specifically want to demonstrate the *presence* of an error, you can add `#| error: true` to the top of the code block in question. |
| 64 | + ::: |
| 65 | + |
| 66 | +2. The workflow that checks that the version of Turing is the newest possible version. |
| 67 | + If this workflow fails, it's because the Manifest file contains an older version of Turing. |
| 68 | + |
| 69 | +Note that the build-docs workflow utilises a lot of caching in order to speed up the build process (a full docs build can take 1.5 hours). |
| 70 | +However, this caching is dependent on the Manifest file not changing. |
| 71 | +Therefore, be aware that if you update the Manifest file, the next workflow run will require a full build! |
| 72 | + |
| 73 | +**If you are writing new docs that do not rely on a newer version of any dependency, it is often better to avoid updating the Manifest file, and instead just add the new docs.** |
| 74 | +In this case, it's fine to let the check-version CI workflow fail. |
| 75 | +You can add a Manifest update in a separate PR. |
0 commit comments