From b780cf35f86b2125cae1c467cf0f5399c8de3185 Mon Sep 17 00:00:00 2001 From: Penelope Yong Date: Fri, 23 Jan 2026 23:08:03 +0000 Subject: [PATCH] Describe how to contribute to docs --- developers/contributing/index.qmd | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/developers/contributing/index.qmd b/developers/contributing/index.qmd index df006a9bb..d71479821 100755 --- a/developers/contributing/index.qmd +++ b/developers/contributing/index.qmd @@ -19,14 +19,37 @@ If you are new to open source software, please see [GitHub's introduction](https ### Documentation +#### Where is Turing's documentation? + 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. For example, the source code for DynamicPPL's documentation can be found in [its repository](https://github.com/TuringLang/DynamicPPL.jl). -The documentation for Turing.jl itself consists of the tutorials that you see on this website, and is built from the separate [`docs` repository](https://github.com/TuringLang/docs). -None of the documentation is generated from the [main Turing.jl repository](https://github.com/TuringLang/Turing.jl); in particular, the API that Turing exports does not currently form part of the documentation. +On top of the library-specific documentation, we also have a general documentation repository, which is what builds the website you are currently reading! +Anything that appears in `turinglang.org/docs` is built from the [`docs` repository](https://github.com/TuringLang/docs). 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). +In general, we prefer documentation to be written on the `TuringLang/docs` repository. +This is because it is more easily discoverable for users via the search bar and sidebar. +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. + +#### Documenting unreleased features + +There are sometimes cases where it is not possible to add docs to the `TuringLang/docs` repository. +In particular, because the `TuringLang/docs` repo builds from a released version of Turing and all its dependencies, new features in unreleased versions cannot be documented here. +However, it's always better to document things as you go along rather than to wait for a release and then play catch-up! +In such instances, we recommend first adding documentation to the relevant package's `docs` folder (using Documenter.jl as usual), and later copying it over to the main `TuringLang/docs` repository (adjusting for the Quarto format) once the new version is released. +Note that because the `TuringLang/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. + +#### Environments + +The `TuringLang/docs` repository is built from a single Manifest file, which contains a pinned version of Turing.jl. +All notebooks are run with the same environment, which ensures consistency across the documentation site. + +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. +The reason for this is because such packages will have compatibility bounds on Turing. +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. + ### Tests Turing, like most software libraries, has a test suite. You can run the whole suite by running `julia --project=.` from the root of the Turing repository, and then running @@ -190,4 +213,4 @@ When adhering to the Blue style, it's important to realise that these are guidel > A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important. -> But most importantly: know when to be inconsistent – sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask! \ No newline at end of file +> But most importantly: know when to be inconsistent – sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!