|
1 | 1 | # Turing.jl Documentation and Tutorials |
2 | 2 |
|
3 | | -**https://turinglang.org/docs/** |
| 3 | +**https://turinglang.org/docs/** |
4 | 4 |
|
5 | | -## Contributing |
| 5 | +## Contributing |
6 | 6 |
|
7 | | -The easiest way to contribute to the documentation is to simply open a pull request. |
8 | | -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. |
9 | | -(Note that if you are editing a tutorial that takes a long time to run, this feedback may take a while.) |
| 7 | +The easiest way to contribute to the documentation is to simply open a pull request. |
| 8 | +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. |
| 9 | +(Note that if you are editing a tutorial that takes a long time to run, this feedback may take a while.) |
10 | 10 |
|
11 | | -The `main` branch contains the Quarto source code. |
12 | | -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. |
| 11 | +The `main` branch contains the Quarto source code. |
| 12 | +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. |
13 | 13 |
|
14 | | -## Local development |
| 14 | +## Local development |
15 | 15 |
|
16 | | -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. |
17 | | -Then: |
| 16 | +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. |
| 17 | +Then: |
18 | 18 |
|
19 | | -1. Clone this repository: |
| 19 | +1. Clone this repository: |
20 | 20 |
|
21 | 21 | ```bash |
22 | 22 | git clone https://github.com/TuringLang/docs |
23 | | - ``` |
| 23 | + ``` |
24 | 24 |
|
25 | | -2. Navigate into the cloned directory: |
| 25 | +2. Navigate into the cloned directory: |
26 | 26 |
|
27 | 27 | ```bash |
28 | 28 | cd docs |
29 | | - ``` |
| 29 | + ``` |
30 | 30 |
|
31 | | -3. Instantiate the project environment: |
| 31 | +3. Instantiate the project environment: |
32 | 32 |
|
33 | 33 | ```bash |
34 | 34 | julia --project=. -e 'using Pkg; Pkg.instantiate()' |
35 | | - ``` |
| 35 | + ``` |
36 | 36 |
|
37 | | -4. Preview the website using Quarto. |
| 37 | +4. Preview the website using Quarto. |
38 | 38 |
|
39 | | -> [!WARNING] |
40 | | -> 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. |
| 39 | +> [!WARNING] |
| 40 | +> 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. |
41 | 41 |
|
42 | 42 | ```bash |
43 | 43 | quarto preview |
44 | | - ``` |
| 44 | + ``` |
45 | 45 |
|
46 | | - 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. |
| 46 | + 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. |
47 | 47 |
|
48 | | -5. Render the website locally: |
| 48 | +5. Render the website locally: |
49 | 49 |
|
50 | 50 | ```bash |
51 | 51 | quarto render |
52 | | - ``` |
| 52 | + ``` |
53 | 53 |
|
54 | | - This will build the entire documentation and place the output in the `_site` folder. |
55 | | - You can then view the rendered website by launching an HTTP server from that directory, e.g. using Python: |
| 54 | + This will build the entire documentation and place the output in the `_site` folder. |
| 55 | + You can then view the rendered website by launching an HTTP server from that directory, e.g. using Python: |
56 | 56 |
|
57 | 57 | ```bash |
58 | 58 | cd _site |
59 | 59 | python -m http.server 8000 |
60 | | - ``` |
| 60 | + ``` |
61 | 61 |
|
62 | | - Then, navigate to http://localhost:8000/ in your web browser. |
| 62 | + Then, navigate to http://localhost:8000/ in your web browser. |
63 | 63 |
|
64 | | -## Faster rendering |
| 64 | +## Faster rendering |
65 | 65 |
|
66 | | -Note that rendering the entire documentation site can take a long time (usually multiple hours). |
67 | | -If you wish to speed up local rendering, there are two options available: |
| 66 | +Note that rendering the entire documentation site can take a long time (usually multiple hours). |
| 67 | +If you wish to speed up local rendering, there are two options available: |
68 | 68 |
|
69 | | -1. Render a single tutorial or `qmd` file without compiling the entire site. |
70 | | - To do this, pass the `qmd` file as an argument to `quarto render`: |
| 69 | +1. Render a single tutorial or `qmd` file without compiling the entire site. |
| 70 | + To do this, pass the `qmd` file as an argument to `quarto render`: |
71 | 71 |
|
72 | 72 | ``` |
73 | 73 | quarto render path/to/index.qmd |
74 | | - ``` |
75 | | - |
76 | | - (Note that `quarto preview` does not support this single-file rendering.) |
| 74 | + ``` |
| 75 | + |
| 76 | + (Note that `quarto preview` does not support this single-file rendering.) |
| 77 | + |
| 78 | +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. |
| 79 | + The `_freeze` folder stores the cached outputs from a previous build of the documentation. |
| 80 | + If it is present, Quarto will reuse the outputs of previous computations for any files for which the source is unchanged. |
77 | 81 |
|
78 | | -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. |
79 | | - The `_freeze` folder stores the cached outputs from a previous build of the documentation. |
80 | | - If it is present, Quarto will reuse the outputs of previous computations for any files for which the source is unchanged. |
| 82 | + 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. |
| 83 | + 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. |
81 | 84 |
|
82 | | - 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. |
83 | | - 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. |
84 | | - |
85 | | - 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). |
| 85 | + 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). |
86 | 86 |
|
87 | | -## Troubleshooting build issues |
| 87 | +## Troubleshooting build issues |
88 | 88 |
|
89 | | -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. |
90 | | -Sometimes this can result in issues with old package code not being unloaded (e.g. when package versions are upgraded). |
91 | | -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: |
| 89 | +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. |
| 90 | +Sometimes this can result in issues with old package code not being unloaded (e.g. when package versions are upgraded). |
| 91 | +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: |
92 | 92 |
|
93 | 93 | ```bash |
94 | 94 | quarto render /path/to/index.qmd --execute-daemon-restart |
95 | | -``` |
| 95 | +``` |
96 | 96 |
|
97 | | -And also, kill any stray Quarto processes that are still running (sometimes it keeps running in the background): |
| 97 | +And also, kill any stray Quarto processes that are still running (sometimes it keeps running in the background): |
98 | 98 |
|
99 | 99 | ```bash |
100 | 100 | pkill -9 -f quarto |
101 | | -``` |
| 101 | +``` |
102 | 102 |
|
103 | | -## License |
| 103 | +## License |
104 | 104 |
|
105 | | -This project is licensed under the MIT License - see the [License](License) file for details. |
| 105 | +This project is licensed under the MIT License - see the [License](License) file for details. |
0 commit comments