forked from quarto-dev/quarto-web
-
Notifications
You must be signed in to change notification settings - Fork 0
/
bug-reports.qmd
152 lines (109 loc) · 4.58 KB
/
bug-reports.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
---
title: "Bug Reports"
subtitle: "How to make an actionable bug report for Quarto"
toc-depth: 3
---
We want to hear about Quarto bugs and, we want to fix those bugs! The following guidance will help us be as efficient as we can.
## Rule 0: Please submit your bug report anyway!
We have a better chance to fix your code quickly if you follow the instructions below. Still, we know that this takes work and isn't always possible.
**We would rather have a record of the problem than not know about it**.
We appreciate bug reports even if you are unable to take any or all of the following steps:
## Small is beautiful: Aim for a single document with \~10 lines
The most helpful thing you can do to help us is to provide a minimal, self-contained, and reproducible example.
- **minimal**: This will often mean turning your large website project into a project with a single small document, and a single large `.qmd` file into a small (ideally, about 10-20 total lines of code) example. By doing this, you might also be able to learn more specifically what the problem is.
- **self-contained**: The more software dependencies we need to understand and install, the harder it is to track the bug down. As you reduce the code, remove as many dependencies as possible.
- **reproducible**: If we cannot run your example, we cannot track the bug down. Please make sure the file you submitted is enough to trigger the bug on its own.
### Formatting: Make GitHub's markdown work for us {#formatting-make-githubs-markdown-work-for-us}
You can share a **minimal** **self-contained** **reproducible** Quarto document using the following markdown syntax, _i.e._, using more backticks than you have in your document (usually four ` ```` `) to account for code cells.
::: {layout-ncol="2"}
`````md
````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: jupyter
---
This is a minimal self-contained reproducible Quarto document using `format: html` and `jupyter` engine.
It is written in Markdown and contains embedded Python code.
```{{python}}
print("Hello, world!")
```
The end.
````
`````
`````md
````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: knitr
---
This is a minimal self-contained reproducible Quarto document using `format: html` and `knitr` engine.
It is written in Markdown and contains embedded R code.
```{{r}}
print("Hello, world!")
```
The end.
````
`````
:::
## Don't hold back: Tell us anything you think might make a difference
Although we want the `.qmd` file to be small, we still can use as much information from you as you're willing to share. Tell us all!, including:
- The version of Quarto you're running
- The operating system you're running
- The IDE you're using, and its version
### Check
You can provide the output (within a code block) of the following command to help us understand your environment:
```bash
quarto check
```
For instance, the markdown code you would provide might look like this:
````md
```bash
Quarto 99.9.9
[✓] Checking versions of quarto binary dependencies...
Pandoc version 3.1.11: OK
Dart Sass version 1.69.5: OK
Deno version 1.37.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
Version: 99.9.9
Path: /quarto-cli/package/dist/bin
[✓] Checking tools....................OK
TinyTeX: v2024.01
Chromium: (not installed)
[✓] Checking LaTeX....................OK
Using: TinyTex
Path: /Users/username/Library/TinyTeX/bin/universal-darwin
Version: 2023
[✓] Checking basic markdown render....OK
[✓] Checking Python 3 installation....OK
Version: 3.12.1
Path: /.venv/bin/python3
Jupyter: 5.7.1
Kernels: julia-1.10, python3
[✓] Checking Jupyter engine render....OK
[✓] Checking R installation...........OK
Version: 4.3.2
Path: /Library/Frameworks/R.framework/Resources
LibPaths:
- /Users/username/Library/Caches/org.R-project.R/R/renv/sandbox/R-4.3/aarch64-apple-darwin20/ac5c2659
knitr: 1.45
rmarkdown: 2.25
[✓] Checking Knitr engine render......OK
```
````
### Print stack
If you are seeing an error from Quarto, you can also provide additional diagnostic information by defining the `QUARTO_PRINT_STACK` environment variable.
For example on Unix:
```bash
export QUARTO_PRINT_STACK=true
quarto render document.qmd
```
or on Windows in a Powershell Terminal
```powershell
$ENV:QUARTO_PRINT_STACK="true"
quarto render document.qmd
```