From b4949a7ebb02e5f8764b992aeca45dd5205a4d51 Mon Sep 17 00:00:00 2001 From: Penelope Yong Date: Wed, 14 Aug 2024 20:51:35 +0100 Subject: [PATCH] Update README following #497 (#506) * Update README following #497 * Specify Quarto minimum version * Streamline instructions for rendering a single file --- README.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index b7f35bc35..742bfd692 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,11 @@ # Documentation and Tutorials for Turing.jl This repository is part of [Turing.jl's](https://turinglang.org/) website (i.e. `https://turinglang.org/docs/`). It contains the Turing.jl documentation and tutorials. - - The `master` branch contains the quarto source - The `gh-pages` branch contains the `html` version of these documents compiled from the `master` branch. -To get started with the docs website locally, you'll need to have the following prerequisite installed: - -- [Quarto](https://quarto.org/docs/download/) +To get started with the docs website locally, you'll need to have [Quarto](https://quarto.org/docs/download/) installed. +Make sure you have at least version 1.5 of Quarto installed, as this is required to correctly run [the native Julia engine](https://quarto.org/docs/computations/julia.html#using-the-julia-engine). Once you have the prerequisite installed, you can follow these steps: @@ -23,27 +21,34 @@ Once you have the prerequisite installed, you can follow these steps: cd docs ``` -3. Preview the website using Quarto Preview: +3. Instantiate the project environment: + + ```bash + julia --project=. -e 'using Pkg; Pkg.instantiate()' + ``` + +4. Preview the website using Quarto Preview: ```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. -Note: Avoid clicking links in the navbar while previewing locally because they will eventually lead to https links online! -4. Render the website locally: + 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. + Note: Avoid clicking links in the navbar while previewing locally because they will eventually lead to https links online! + +5. Render the website locally: ```bash quarto render ``` -This will render the full website in `_site` folder. -It is also possible to render a single tutorial or `qmd` file without compiling the entire site. This is often helpful to speed up compilation when editing a single docs page. To do this, first `cd` to the file's folder, and run `quarto preview` or `quarto render`: + This will render the full website in `_site` folder. + + It is also possible to render a single tutorial or `qmd` file without compiling the entire site. This is often helpful to speed up compilation when editing a single docs page. To do this, pass the `qmd` file as an argument to `quarto render`: -``` -cd somedocs # This is the folder containing a docs `qmd` file. -quarto render index.qmd -``` + ``` + quarto render path/to/index.qmd + ``` ## License