diff --git a/docs/get-started/computations/_footer.md b/docs/get-started/computations/_footer.md index 819f2f3cd8..742378730e 100644 --- a/docs/get-started/computations/_footer.md +++ b/docs/get-started/computations/_footer.md @@ -2,6 +2,6 @@ You've now covered the basics of customizing the behavior and output of executable code in Quarto documents. -Next, check out the [Authoring Tutorial](../authoring/) to learn more about output formats and technical writing features like citations, crossrefs, and advanced layout. +Next, check out the [Authoring Tutorial](../authoring/{{< meta tool.name >}}.qmd) to learn more about output formats and technical writing features like citations, crossrefs, and advanced layout. diff --git a/docs/get-started/computations/_text-editor.md b/docs/get-started/computations/_text-editor.md new file mode 100644 index 0000000000..f16a7b9b36 --- /dev/null +++ b/docs/get-started/computations/_text-editor.md @@ -0,0 +1,258 @@ +{{< include ../_tool-chooser.md >}} + +## Overview + +Quarto has a wide variety of options available for controlling how code and computational output appear within rendered documents. +In this tutorial we'll take a `.qmd` file that has some numeric output and plots, and cover how to apply these options. + +This tutorial will make use of the `matplotlib` and `plotly` Python packages. +The commands you can use to install them are given in the table below. + ++-----------+---------------------------------------------------------+ +| Platform | Commands | ++===========+=========================================================+ +| Mac/Linux | ```{.bash filename="Terminal"} | +| | python3 -m pip install jupyter matplotlib plotly pandas | +| | ``` | ++-----------+---------------------------------------------------------+ +| Windows | ```{.powershell filename="Terminal"} | +| | py -m pip install jupyter matplotlib plotly pandas | +| | ``` | ++-----------+---------------------------------------------------------+ + +If you want to follow along step-by-step in your own environment, create a `computations.qmd` file and copy the following content into it. + +```` markdown +--- +title: Quarto Computations +jupyter: python3 +--- + +## NumPy + +```{{python}} +import numpy as np +a = np.arange(15).reshape(3, 5) +a +``` + +## Matplotlib + +```{{python}} +import matplotlib.pyplot as plt + +fig = plt.figure() +x = np.arange(10) +y = 2.5 * np.sin(x / 20 * np.pi) +yerr = np.linspace(0.05, 0.2, 10) + +plt.errorbar(x, y + 3, yerr=yerr, label='both limits (default)') +plt.errorbar(x, y + 2, yerr=yerr, uplims=True, label='uplims=True') +plt.errorbar(x, y + 1, yerr=yerr, uplims=True, lolims=True, + label='uplims=True, lolims=True') + +upperlimits = [True, False] * 5 +lowerlimits = [False, True] * 5 +plt.errorbar(x, y, yerr=yerr, uplims=upperlimits, lolims=lowerlimits, + label='subsets of uplims and lolims') + +plt.legend(loc='lower right') +plt.show(fig) +``` + +## Plotly + +```{{python}} +import plotly.express as px +import plotly.io as pio +gapminder = px.data.gapminder() +gapminder2007 = gapminder.query("year == 2007") +fig = px.scatter(gapminder2007, + x="gdpPercap", y="lifeExp", color="continent", + size="pop", size_max=60, + hover_name="country") +fig.show() +``` +```` + +Now, open a Terminal and run `quarto preview`, then position your editor side-by-side with the browser showing the preview. + +``` {.bash filename="Terminal"} +quarto preview computations.qmd +``` + +![](images/text-editor-computations-preview.png){.border .column-page-outset-right fig-alt="Side-by-side preview of text editor on the left and live preview in the browser on the right."} + +## Cell Output + +All of the code in the source file is displayed within the rendered document. +However, in some cases, you may want to hide all of the code and just show the output. +Let's go ahead and specify `echo: false` within the document `execute` options to prevent code from being printed. + +``` yaml +--- +title: Quarto Computations +execute: + echo: false +jupyter: python3 +--- +``` + +Save the file after making this change. +The preview will update to show the output with no code. + +![](images/exec-echo-false-preview.png){.border fig-alt="Output of computations.qmd with 'echo: false' set, shows Title, resulting array in NumPy section, line chart in Matplotlib section, and interactive bubble chart in Plotly section."} + +You might want to selectively enable code `echo` for some cells. +To do this add the `echo: true` cell option. +Try this with the NumPy cell. + +```` markdown +```{{python}} +#| echo: true + +import numpy as np +a = np.arange(15).reshape(3, 5) +a +``` +```` + +Save the file and note that the code is now included for the NumPy cell. + +![](images/exec-echo-true-preview.png){.border fig-alt="Rendered NumPy section of computations.qmd which shows the code and the resulting array."} + +There a large number of other options available for cell output, for example `warning` to show/hide warnings (which can be especially helpful for package loading messages), `include` as a catch all for preventing any output (code or results) from being included in output, and `error` to prevent errors in code execution from halting the rendering of the document (and print the error in the rendered document). + +See the [Jupyter Cell Options](/docs/reference/cells/cells-jupyter.qmd) documentation for additional details. + +## Code Folding + +Rather than hiding code entirely, you might want to fold it and allow readers to view it at their discretion. +You can do this via the `code-fold` option. +Remove the `echo` option we previously added and add the `code-fold` HTML format option. + +``` yaml +--- +title: Quarto Computations +format: + html: + code-fold: true +jupyter: python3 +--- +``` + +Save the file. +Now a "Code" widget is available above the output of each cell. + +![](images/code-fold-preview.png){.border fig-alt="Rendered NumPy section of computations.qmd which shows a toggleable section that is labelled 'Code' and the resulting array."} + +You can also provide global control over code folding. +Try adding `code-tools: true` to the HTML format options. + +``` yaml +--- +title: Quarto Computations +format: + html: + code-fold: true + code-tools: true +jupyter: python3 +--- +``` + +Save the file and you'll see that a code menu appears at the top right of the document that provides global control over showing and hiding code. + +![](images/text-editor-code-tools-preview.png){.border fig-alt="Rendered version of the computations.qmd document. A new code widget appears on top right of the document. The screenshot shows that the widget is clicked on, which reveals a drop down menu with three choices: Show All Code, Hide All Code, and View Source. In the background is the rendered document. The title is followed by some text, which is followed by a Code widget that would expand if clicked on, which is followed by the output of the code. The Code widgets are folded, so the code is not visible in the rendered document."} + +## Figures + +Let's improve the appearance of our Matplotlib output. +It could certainly stand to be wider, and it would be nice to provide a caption and a label for cross-referencing. + +Go ahead and modify the Matplotlib cell to include `label` and `fig-cap` options as well as a call to `fig.set_size_inches()` to set a larger figure size with a wider aspect ratio: + +```` markdown +```{{python}} +#| label: fig-limits +#| fig-cap: "Errorbar limit selector" + +import matplotlib.pyplot as plt + +fig = plt.figure() +fig.set_size_inches(12, 7) +``` +```` + +Save the file to re-render and see the updated plot: + +![](images/figure-options-preview.png){.border fig-alt="Rendered Matplotlib section of computations.qmd which includes a toggleable code-folding widget, the figure, and a caption under the figure that reads 'Figure 1: Errorbar limit selection.'"} + +## Multiple Figures + +The Plotly cell visualizes GDP and life expectancy data from a single year (2007). +Let's plot another year next to it for comparison and add a caption and subcaptions. +Since this will produce a wider visualization we'll also use the `column` option to lay it out across the entire page rather than being constrained to the body text column. + +There are quite a few changes to this cell. +Copy and paste this code into `computations.qmd` if you want to try them locally: + +``` python +#| label: fig-gapminder +#| fig-cap: "Life Expectancy and GDP" +#| fig-subcap: +#| - "Gapminder: 1957" +#| - "Gapminder: 2007" +#| layout-ncol: 2 +#| column: page + +import plotly.express as px +import plotly.io as pio +gapminder = px.data.gapminder() +def gapminder_plot(year): + gapminderYear = gapminder.query("year == " + + str(year)) + fig = px.scatter(gapminderYear, + x="gdpPercap", y="lifeExp", + size="pop", size_max=60, + hover_name="country") + fig.show() + +gapminder_plot(1957) +gapminder_plot(2007) +``` + +Save the file, the preview will update as follows: + +![](images/plotly-preview.png){.border fig-alt="Output of Plotly section which shows two charts side-by-side. The first has a caption below that reads '(a) Gapminder: 1957', the second's caption reads '(b) Gapminder 2007'. Below both figures, there's a caption that reads 'Figure 1: Life Expectancy and GDP (Data from World Bank via gapminder.org).'"} + +Let's discuss some of the new options used here. +You've seen `fig-cap` before but we've now added a `fig-subcap` option: + +``` python +#| fig-cap: "Life Expectancy and GDP" +#| fig-subcap: +#| - "Gapminder: 1957" +#| - "Gapminder: 2007" +``` + +For code cells with multiple outputs adding the `fig-subcap` option enables us to treat them as subfigures. + +We also added an option to control how multiple figures are laid out---in this case we specified side-by-side in two columns: + +``` python +#| layout-ncol: 2 +``` + +If you have 3, 4, or more figures in a panel there are many options available for customizing their layout. +See the article [Figures](/docs/authoring/figures.qmd) for details. + +Finally, we added an option to control the span of the page that our figures occupy: + +``` python +#| column: page +``` + +This allows our figure display to span out beyond the normal body text column. +See the documentation on [Article Layout](/docs/authoring/article-layout.qmd) to learn about all of the available layout options. + +{{< include _footer.md >}} diff --git a/docs/get-started/computations/jupyter.qmd b/docs/get-started/computations/jupyter.qmd index 889b7de653..72599edd2a 100644 --- a/docs/get-started/computations/jupyter.qmd +++ b/docs/get-started/computations/jupyter.qmd @@ -3,6 +3,8 @@ title: "Tutorial: Computations" editor_options: markdown: wrap: sentence +tool: + name: jupyter --- {{< include ../_tool-chooser.md >}} diff --git a/docs/get-started/computations/neovim.qmd b/docs/get-started/computations/neovim.qmd index f409b42a9f..a33701bcc6 100644 --- a/docs/get-started/computations/neovim.qmd +++ b/docs/get-started/computations/neovim.qmd @@ -1 +1,11 @@ -{{< include text-editor.qmd >}} \ No newline at end of file +--- +title: "Tutorial: Computations" +editor_options: + markdown: + wrap: sentence + canonical: true +tool: + name: neovim +--- + +{{< include _text-editor.md >}} \ No newline at end of file diff --git a/docs/get-started/computations/rstudio.qmd b/docs/get-started/computations/rstudio.qmd index 48b577f301..9caa29c460 100644 --- a/docs/get-started/computations/rstudio.qmd +++ b/docs/get-started/computations/rstudio.qmd @@ -4,6 +4,8 @@ editor_options: markdown: wrap: sentence canonical: true +tool: + name: rstudio --- {{< include ../_tool-chooser.md >}} diff --git a/docs/get-started/computations/text-editor.qmd b/docs/get-started/computations/text-editor.qmd index d23b3ed695..acc862dbf3 100644 --- a/docs/get-started/computations/text-editor.qmd +++ b/docs/get-started/computations/text-editor.qmd @@ -4,263 +4,8 @@ editor_options: markdown: wrap: sentence canonical: true +tool: + name: text-editor --- -{{< include ../_tool-chooser.md >}} - -## Overview - -Quarto has a wide variety of options available for controlling how code and computational output appear within rendered documents. -In this tutorial we'll take a `.qmd` file that has some numeric output and plots, and cover how to apply these options. - -This tutorial will make use of the `matplotlib` and `plotly` Python packages. -The commands you can use to install them are given in the table below. - -+-----------+---------------------------------------------------------+ -| Platform | Commands | -+===========+=========================================================+ -| Mac/Linux | ```{.bash filename="Terminal"} | -| | python3 -m pip install jupyter matplotlib plotly pandas | -| | ``` | -+-----------+---------------------------------------------------------+ -| Windows | ```{.powershell filename="Terminal"} | -| | py -m pip install jupyter matplotlib plotly pandas | -| | ``` | -+-----------+---------------------------------------------------------+ - -If you want to follow along step-by-step in your own environment, create a `computations.qmd` file and copy the following content into it. - -```` markdown ---- -title: Quarto Computations -jupyter: python3 ---- - -## NumPy - -```{{python}} -import numpy as np -a = np.arange(15).reshape(3, 5) -a -``` - -## Matplotlib - -```{{python}} -import matplotlib.pyplot as plt - -fig = plt.figure() -x = np.arange(10) -y = 2.5 * np.sin(x / 20 * np.pi) -yerr = np.linspace(0.05, 0.2, 10) - -plt.errorbar(x, y + 3, yerr=yerr, label='both limits (default)') -plt.errorbar(x, y + 2, yerr=yerr, uplims=True, label='uplims=True') -plt.errorbar(x, y + 1, yerr=yerr, uplims=True, lolims=True, - label='uplims=True, lolims=True') - -upperlimits = [True, False] * 5 -lowerlimits = [False, True] * 5 -plt.errorbar(x, y, yerr=yerr, uplims=upperlimits, lolims=lowerlimits, - label='subsets of uplims and lolims') - -plt.legend(loc='lower right') -plt.show(fig) -``` - -## Plotly - -```{{python}} -import plotly.express as px -import plotly.io as pio -gapminder = px.data.gapminder() -gapminder2007 = gapminder.query("year == 2007") -fig = px.scatter(gapminder2007, - x="gdpPercap", y="lifeExp", color="continent", - size="pop", size_max=60, - hover_name="country") -fig.show() -``` -```` - -Now, open a Terminal and run `quarto preview`, then position your editor side-by-side with the browser showing the preview. - -``` {.bash filename="Terminal"} -quarto preview computations.qmd -``` - -![](images/text-editor-computations-preview.png){.border .column-page-outset-right fig-alt="Side-by-side preview of text editor on the left and live preview in the browser on the right."} - -## Cell Output - -All of the code in the source file is displayed within the rendered document. -However, in some cases, you may want to hide all of the code and just show the output. -Let's go ahead and specify `echo: false` within the document `execute` options to prevent code from being printed. - -``` yaml ---- -title: Quarto Computations -execute: - echo: false -jupyter: python3 ---- -``` - -Save the file after making this change. -The preview will update to show the output with no code. - -![](images/exec-echo-false-preview.png){.border fig-alt="Output of computations.qmd with 'echo: false' set, shows Title, resulting array in NumPy section, line chart in Matplotlib section, and interactive bubble chart in Plotly section."} - -You might want to selectively enable code `echo` for some cells. -To do this add the `echo: true` cell option. -Try this with the NumPy cell. - -```` markdown -```{{python}} -#| echo: true - -import numpy as np -a = np.arange(15).reshape(3, 5) -a -``` -```` - -Save the file and note that the code is now included for the NumPy cell. - -![](images/exec-echo-true-preview.png){.border fig-alt="Rendered NumPy section of computations.qmd which shows the code and the resulting array."} - -There a large number of other options available for cell output, for example `warning` to show/hide warnings (which can be especially helpful for package loading messages), `include` as a catch all for preventing any output (code or results) from being included in output, and `error` to prevent errors in code execution from halting the rendering of the document (and print the error in the rendered document). - -See the [Jupyter Cell Options](/docs/reference/cells/cells-jupyter.qmd) documentation for additional details. - -## Code Folding - -Rather than hiding code entirely, you might want to fold it and allow readers to view it at their discretion. -You can do this via the `code-fold` option. -Remove the `echo` option we previously added and add the `code-fold` HTML format option. - -``` yaml ---- -title: Quarto Computations -format: - html: - code-fold: true -jupyter: python3 ---- -``` - -Save the file. -Now a "Code" widget is available above the output of each cell. - -![](images/code-fold-preview.png){.border fig-alt="Rendered NumPy section of computations.qmd which shows a toggleable section that is labelled 'Code' and the resulting array."} - -You can also provide global control over code folding. -Try adding `code-tools: true` to the HTML format options. - -``` yaml ---- -title: Quarto Computations -format: - html: - code-fold: true - code-tools: true -jupyter: python3 ---- -``` - -Save the file and you'll see that a code menu appears at the top right of the document that provides global control over showing and hiding code. - -![](images/text-editor-code-tools-preview.png){.border fig-alt="Rendered version of the computations.qmd document. A new code widget appears on top right of the document. The screenshot shows that the widget is clicked on, which reveals a drop down menu with three choices: Show All Code, Hide All Code, and View Source. In the background is the rendered document. The title is followed by some text, which is followed by a Code widget that would expand if clicked on, which is followed by the output of the code. The Code widgets are folded, so the code is not visible in the rendered document."} - -## Figures - -Let's improve the appearance of our Matplotlib output. -It could certainly stand to be wider, and it would be nice to provide a caption and a label for cross-referencing. - -Go ahead and modify the Matplotlib cell to include `label` and `fig-cap` options as well as a call to `fig.set_size_inches()` to set a larger figure size with a wider aspect ratio: - -```` markdown -```{{python}} -#| label: fig-limits -#| fig-cap: "Errorbar limit selector" - -import matplotlib.pyplot as plt - -fig = plt.figure() -fig.set_size_inches(12, 7) -``` -```` - -Save the file to re-render and see the updated plot: - -![](images/figure-options-preview.png){.border fig-alt="Rendered Matplotlib section of computations.qmd which includes a toggleable code-folding widget, the figure, and a caption under the figure that reads 'Figure 1: Errorbar limit selection.'"} - -## Multiple Figures - -The Plotly cell visualizes GDP and life expectancy data from a single year (2007). -Let's plot another year next to it for comparison and add a caption and subcaptions. -Since this will produce a wider visualization we'll also use the `column` option to lay it out across the entire page rather than being constrained to the body text column. - -There are quite a few changes to this cell. -Copy and paste this code into `computations.qmd` if you want to try them locally: - -``` python -#| label: fig-gapminder -#| fig-cap: "Life Expectancy and GDP" -#| fig-subcap: -#| - "Gapminder: 1957" -#| - "Gapminder: 2007" -#| layout-ncol: 2 -#| column: page - -import plotly.express as px -import plotly.io as pio -gapminder = px.data.gapminder() -def gapminder_plot(year): - gapminderYear = gapminder.query("year == " + - str(year)) - fig = px.scatter(gapminderYear, - x="gdpPercap", y="lifeExp", - size="pop", size_max=60, - hover_name="country") - fig.show() - -gapminder_plot(1957) -gapminder_plot(2007) -``` - -Save the file, the preview will update as follows: - -![](images/plotly-preview.png){.border fig-alt="Output of Plotly section which shows two charts side-by-side. The first has a caption below that reads '(a) Gapminder: 1957', the second's caption reads '(b) Gapminder 2007'. Below both figures, there's a caption that reads 'Figure 1: Life Expectancy and GDP (Data from World Bank via gapminder.org).'"} - -Let's discuss some of the new options used here. -You've seen `fig-cap` before but we've now added a `fig-subcap` option: - -``` python -#| fig-cap: "Life Expectancy and GDP" -#| fig-subcap: -#| - "Gapminder: 1957" -#| - "Gapminder: 2007" -``` - -For code cells with multiple outputs adding the `fig-subcap` option enables us to treat them as subfigures. - -We also added an option to control how multiple figures are laid out---in this case we specified side-by-side in two columns: - -``` python -#| layout-ncol: 2 -``` - -If you have 3, 4, or more figures in a panel there are many options available for customizing their layout. -See the article [Figures](/docs/authoring/figures.qmd) for details. - -Finally, we added an option to control the span of the page that our figures occupy: - -``` python -#| column: page -``` - -This allows our figure display to span out beyond the normal body text column. -See the documentation on [Article Layout](/docs/authoring/article-layout.qmd) to learn about all of the available layout options. - -{{< include _footer.md >}} +{{< include _text-editor.md >}} diff --git a/docs/get-started/computations/vscode.qmd b/docs/get-started/computations/vscode.qmd index 202dbf3aa2..0c734d8b0a 100644 --- a/docs/get-started/computations/vscode.qmd +++ b/docs/get-started/computations/vscode.qmd @@ -4,6 +4,8 @@ editor_options: markdown: wrap: sentence canonical: true +tool: + name: vscode --- {{< include ../_tool-chooser.md >}} diff --git a/docs/get-started/hello/_footer.md b/docs/get-started/hello/_footer.md index 509dd455a4..3e1627f7af 100644 --- a/docs/get-started/hello/_footer.md +++ b/docs/get-started/hello/_footer.md @@ -2,6 +2,6 @@ You now know the basics of creating and authoring Quarto documents. The following tutorials explore Quarto in more depth: -- [Tutorial: Computations](../computations/) --- Learn how to tailor the behavior and output of executable code blocks. +- [Tutorial: Computations](../computations/{{< meta tool.name >}}.qmd) --- Learn how to tailor the behavior and output of executable code blocks. -- [Tutorial: Authoring](../authoring/) --- Learn more about output formats and technical writing features like citations, crossrefs, and advanced layout. +- [Tutorial: Authoring](../authoring/{{< meta tool.name >}}.qmd) --- Learn more about output formats and technical writing features like citations, crossrefs, and advanced layout. diff --git a/docs/get-started/hello/jupyter.qmd b/docs/get-started/hello/jupyter.qmd index 6fc92ed34b..656a546c1c 100644 --- a/docs/get-started/hello/jupyter.qmd +++ b/docs/get-started/hello/jupyter.qmd @@ -4,6 +4,8 @@ editor_options: markdown: wrap: sentence canonical: true +tool: + name: jupyter --- {{< include ../_tool-chooser.md >}} diff --git a/docs/get-started/hello/neovim.qmd b/docs/get-started/hello/neovim.qmd index 66b2793e14..b1a1c86574 100644 --- a/docs/get-started/hello/neovim.qmd +++ b/docs/get-started/hello/neovim.qmd @@ -4,6 +4,8 @@ editor_options: markdown: wrap: sentence canonical: true +tool: + name: neovim --- {{< include ../_tool-chooser.md >}} @@ -220,10 +222,6 @@ See Amy Cesal's article on [Writing Alt Text for Data Visualization](https://med ## Next Up -You now know the basics of creating and authoring Quarto documents. The following tutorials explore Quarto in more depth: - -- [Tutorial: Computations](/docs/get-started/computations/index.qmd) --- Learn how to tailor the behavior and output of executable code blocks. - -- [Tutorial: Authoring](/docs/get-started/authoring/index.qmd) --- Learn more about output formats and technical writing features like citations, crossrefs, and advanced layout. +{{< include _footer.md >}} See the article on [Using Neovim with Quarto](/docs/tools/neovim.qmd) to learn more about installing, using, and customizing Neovim for Quarto. diff --git a/docs/get-started/hello/rstudio.qmd b/docs/get-started/hello/rstudio.qmd index 5a1ff3741d..5b00888188 100644 --- a/docs/get-started/hello/rstudio.qmd +++ b/docs/get-started/hello/rstudio.qmd @@ -4,6 +4,8 @@ editor_options: markdown: wrap: sentence canonical: true +tool: + name: rstudio --- {{< include ../_tool-chooser.md >}} diff --git a/docs/get-started/hello/text-editor.qmd b/docs/get-started/hello/text-editor.qmd index 1c4143c66b..19a81c758f 100644 --- a/docs/get-started/hello/text-editor.qmd +++ b/docs/get-started/hello/text-editor.qmd @@ -4,6 +4,8 @@ editor_options: markdown: wrap: sentence canonical: true +tool: + name: text-editor --- {{< include ../_tool-chooser.md >}} diff --git a/docs/get-started/hello/vscode.qmd b/docs/get-started/hello/vscode.qmd index 5ff6896d25..b5edd9161e 100644 --- a/docs/get-started/hello/vscode.qmd +++ b/docs/get-started/hello/vscode.qmd @@ -4,6 +4,8 @@ editor_options: markdown: wrap: sentence canonical: true +tool: + name: vscode --- {{< include ../_tool-chooser.md >}}