-
Notifications
You must be signed in to change notification settings - Fork 105
Various, minor, grammar changes and fixes #655
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 9 commits
03b1b6f
8eb9d6e
13939b5
1191c62
a9d5ef9
2a73b0a
d98fdb0
96faf58
94e1a6f
0c7f940
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -28,4 +28,5 @@ venv | |
site_libs | ||
.DS_Store | ||
index_files | ||
digest.txt | ||
digest.txt | ||
*.bak |
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -1,106 +1,105 @@ | ||||||
# Turing.jl Documentation and Tutorials | ||||||
|
||||||
**https://turinglang.org/docs/** | ||||||
**https://turinglang.org/docs/** | ||||||
|
||||||
## Contributing | ||||||
## Contributing | ||||||
|
||||||
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.) | ||||||
The easiest way to contribute to the documentation is to simply open a pull request. | ||||||
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. | ||||||
(Note that if you are editing a tutorial that takes a long time to run, this feedback may take a while.) | ||||||
|
||||||
The `main` branch contains the Quarto source code. | ||||||
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. | ||||||
The `main` branch contains the Quarto source code. | ||||||
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. | ||||||
|
||||||
## Local development | ||||||
## Local development | ||||||
|
||||||
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. | ||||||
Then: | ||||||
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. | ||||||
Then: | ||||||
|
||||||
1. Clone this repository: | ||||||
1. Clone this repository: | ||||||
|
||||||
```bash | ||||||
git clone https://github.com/TuringLang/docs | ||||||
``` | ||||||
``` | ||||||
|
||||||
2. Navigate into the cloned directory: | ||||||
2. Navigate into the cloned directory: | ||||||
|
||||||
```bash | ||||||
cd docs | ||||||
``` | ||||||
``` | ||||||
|
||||||
3. Instantiate the project environment: | ||||||
3. Instantiate the project environment: | ||||||
|
||||||
```bash | ||||||
julia --project=. -e 'using Pkg; Pkg.instantiate()' | ||||||
``` | ||||||
``` | ||||||
|
||||||
4. Preview the website using Quarto. | ||||||
4. Preview the website using Quarto. | ||||||
|
||||||
> [!WARNING] | ||||||
> 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. | ||||||
> [!WARNING] | ||||||
> 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. | ||||||
|
||||||
```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. | ||||||
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. | ||||||
|
||||||
5. Render the website locally: | ||||||
5. Render the website locally: | ||||||
|
||||||
```bash | ||||||
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: | ||||||
This will build the entire documentation and place the output in the `_site` folder. | ||||||
You can then view the rendered website by launching an HTTP server from that directory, e.g. using Python: | ||||||
|
||||||
```bash | ||||||
cd _site | ||||||
python -m http.server 8000 | ||||||
``` | ||||||
``` | ||||||
|
||||||
Then, navigate to http://localhost:8000/ in your web browser. | ||||||
Then, navigate to http://localhost:8000/ in your web browser. | ||||||
|
||||||
## Faster rendering | ||||||
## Faster rendering | ||||||
|
||||||
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: | ||||||
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 or `qmd` file without compiling the entire site. | ||||||
To do this, pass the `qmd` file as an argument to `quarto render`: | ||||||
1. Render a single tutorial or `qmd` file without compiling the entire site. | ||||||
To do this, pass the `qmd` file as an argument to `quarto render`: | ||||||
|
||||||
``` | ||||||
quarto render path/to/index.qmd | ||||||
``` | ||||||
|
||||||
(Note that `quarto preview` does not support this single-file rendering.) | ||||||
``` | ||||||
(Note that `quarto preview` does not support this single-file rendering.) | ||||||
|
||||||
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. | ||||||
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. | ||||||
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. | ||||||
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, the `Manifest.toml` is also provided, and you should also download this and place it in the root directory of the docs. | ||||||
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, the `Manifest.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 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.) | ||||||
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). | ||||||
|
||||||
## Troubleshooting build issues | ||||||
## Troubleshooting build issues | ||||||
|
||||||
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. | ||||||
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 the `quarto render` command: | ||||||
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. | ||||||
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 the `quarto render` command: | ||||||
|
||||||
```bash | ||||||
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): | ||||||
And also, kill any stray Quarto processes that are still running (sometimes it keeps running in the background): | ||||||
|
||||||
```bash | ||||||
pkill -9 -f quarto | ||||||
``` | ||||||
``` | ||||||
|
||||||
## License | ||||||
## License | ||||||
|
||||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. | ||||||
This project is licensed under the MIT License - see the [License](License) file for details. | ||||||
|
This project is licensed under the MIT License - see the [License](License) file for details. | |
This project is licensed under the MIT License - see the [License](LICENSE) file for details. |
The link breaks if the capitalisation doesn't match the filename.
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -208,7 +208,7 @@ format: | |
|
||
</div> | ||
<div class="footer-bottom"> | ||
<p>Turing.jl was created by <a href="https://mlg.eng.cam.ac.uk/hong/" target="_blank" rel="noopener">Hong Ge</a>, and maintained by the core <a href="https://turinglang.org/team/" target="_blank" rel="noopener">team</a> of developers and <a href="https://github.com/TuringLang/Turing.jl/graphs/contributors" target="_blank" rel="noopener">contributors</a>.<br>© 2025 The Turing Project Contributors. <a href="https://github.com/TuringLang/Turing.jl/blob/master/LICENCE" target="_blank" rel="noopener">MIT License</a>.</p> | ||
<p>Turing.jl was created by <a href="https://mlg.eng.cam.ac.uk/hong/" target="_blank" rel="noopener">Hong Ge</a>, and maintained by the core <a href="https://turinglang.org/team/" target="_blank" rel="noopener">team</a> of developers and <a href="https://github.com/TuringLang/Turing.jl/graphs/contributors" target="_blank" rel="noopener">contributors</a>.<br>© 2025 The Turing Project Contributors. <a href="https://github.com/TuringLang/Turing.jl/blob/master/LICENSE" target="_blank" rel="noopener">MIT License</a>.</p> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm confused by this one. https://github.com/TuringLang/Turing.jl/blob/master/LICENCE, the old link, seems to be correct, no? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Lemme check, I realised in my haste to fix spellings that I broke a file / ref link so maybe I double corrected. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ping me for a rereview once you're done. |
||
<a href="https://github.com/TuringLang/docs/" target="_blank" rel="noopener" class="footer-source-link"><i class="bi bi-github"></i> Website Source</a> | ||
</div> | ||
</div> | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this file just getting a lot of trailing whitespace added, or am I missing something?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, I was having weird markdown rendering for me, so I assumed it was some kind of needing extra space. Fixed in last commit.