Repository files navigation

https://turinglang.org/docs/

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.)

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

If you wish to render the docs website locally, you'll need to haveQuarto installed (at least version 1.6.31) on your computer.Then:

1. Clone this repository:

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

2. Navigate into the cloned directory:

   cd docs

3. Instantiate the project environment:

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

4. Preview the website using Quarto.

   [!WARNING]

   This will take avery long time, as it will build every tutorial from scratch. Seebelow for ways to speed this up.

   quarto preview

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

5. Render the website locally:

   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:

   cd _sitepython -m http.server 8000

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

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 orqmd file without compiling the entire site.To do this, pass theqmd file as an argument toquarto render:

   quarto render path/to/index.qmd

   (Note thatquarto preview does not support this single-file rendering.)

2. Download the most recent_freeze folder from theGitHub releases of this repo, 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, theManifest.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 bytriggering a run for thecreate_release.yml workflow.(You will need to have the appropriate permissions; please create an issue if you need help with this.)

As described in theQuarto docs, 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 thequarto render command:

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):

pkill -9 -f quarto

This project is licensed under the MIT License - see theLICENSE file for details.