Crearea foilor de lucru pentru tutorial; Profiluri de quarto pentru câștig!

Introducere

Am postat anterior despre crearea de foi de lucru pentru 4 motoare cu cvarto diferite (pentru R, Python, Stata și Julia) folosind conținut condiționat. Cu toate acestea, această abordare este un pic hacky și nu am fost foarte mulțumită de ea.

Datorită unei viniete de Christophe Dervieux în pachetul Quarto R, mi -am dat seama că există o modalitate mai convenabilă și mai puțin hacky, de a crea documente tutoriale folosind profiluri de quarto. Nu folosesc abordarea dinamică a metadatelor din vinie pentru a -mi realiza soluția, dar m -a condus la pagina de documentare a quarto -ului relevantă și o discut la sfârșitul acestei postări.

Scopul meu este următorul

Pentru a avea un singur document de cvarto din care atât documentele de întrebare, cât și de soluție pot fi redate pentru un tutorial.

Ca amintire, așa cum am arătat în postarea mea anterioară, acest lucru a fost posibil să obțină de mult timp cu R Markdown și Knitr, deoarece datorită lucrării strălucitoare a lui Yihui Xie, deoarece permit opțiuni de chunk programtice. Prin urmare, implementarea acestui lucru într -un document quarto folosind motorul KNITR este, de asemenea, mai mare și nu îl voi repeta în această postare. Cu toate acestea, celelalte trei motoare cu quarto (pentru Python, Stata și Julia) sunt interesate de care sunt problematice, deoarece, din câte știu, nu permit opțiuni de bucată programică și nu au echivalentul ! expr ... Yaml Tag literal.

Profiluri de quarto

Profiluri de quarto sunt introduse pe această pagină a documentației Quarto. Mai exact, vom folosi conținutul condiționat dependent de profil.

Mai întâi vom crea un simplu fișier de profil de quarto implicit _quarto.yml care va conține pur și simplu următoarele.

execute:
  eval: true

)

În continuare pentru fiecare limbă, voi face profiluri pentru ieșirea întrebărilor și a soluțiilor de ieșire în fișiere YAML numite corespunzător (arăt doar fișierele Python ca celelalte două doar Stata/Julia înlocuite în locurile Appropraite).

Profiluri de întrebări și soluții pentru Python

_quarto-python-questions.yml

project:
  render:
    - tutorial-python.qmd
title: 'Questions document: Python version'
execute:
  eval: false

_quarto-python-solutions.yml

project:
  render:
    - tutorial-python.qmd
title: 'Solutions document: Python version'

Atunci documentul nostru de quarto Python, tutorial, Tutorial-Python.QMDva arăta ca următoarele.

---
format:
  html:
    embed-resources: true
jupyter: python3
---

## Question 1

Question text.

```{python}
print("The code which is echoed in questions and evaluated in solutions.")
```

::: {.content-visible when-profile="python-solutions"}
The text for the solutions.
:::

Vedem utilizarea conținutului condiționat pe baza profilului pentru textul soluțiilor și am putea include bucăți suplimentare de cod în aceste divs de conținut condiționat.

Repetăm ​​acest lucru pentru celelalte 2 motoare cu quarto complicate, engine: julia şi jupyter: nbstatainclusiv realizarea de fișiere YAML de profil pentru fiecare motor și respectivul Tutorial- {Stata/Julia} .Qmd Documente de cvarto.

Apoi facem un script shell cu comenzile noastre de redare.

quarto render --profile python-questions -o tutorial-python-questions.html
quarto render --profile python-solutions -o tutorial-python-solutions.html

quarto render --profile stata-questions -o tutorial-stata-questions.html
quarto render --profile stata-solutions -o tutorial-stata-solutions.html

quarto render --profile julia-questions -o tutorial-julia-questions.html
quarto render --profile julia-solutions -o tutorial-julia-solutions.html

Și pentru că am o versiune R folosind parametri scriptul meu de shell începe de obicei.

quarto render tutorial-r.qmd -P solutions:false -o tutorial-r-questions.html
quarto render tutorial-r.qmd -o tutorial-r-solutions.html

Și asta este.

Puteți găsi codul sursă complet în exemplul meu Repo aici, iar ieșirea lor redată poate fi vizualizată de aici. Acest repo conține, de asemenea, un document de tutorial, inclusiv cele 4 limbi din același document folosind codul scurt încorporat așa cum am descris într -o altă postare anterioară. Mai sus este prezentată o captură de ecran a documentelor de întrebări și soluții din această abordare.

Când am început să citesc vinietul pachetului quarto r, am început să încerc să folosesc metadate dinamice pentru a obține rezultatul de mai sus. Metadatele dinamice implică scrierea blocurilor YAML suplimentare în documentul dvs. Quarto, care poate include valori specificate programatic ale parametrilor, care pot fi apoi utilizate prin includerea conținutului condiționat prin potrivirea cu ei. Am descoperit că pot realiza ceea ce îmi doream, cu excepția modificării execute Starea documentului Quarto, se pare că trebuie specificat în primul bloc/antet YAML. Și acest lucru nu poate fi controlat de --execute şi --no-execute steaguri la quarto render Deoarece unul are nevoie de codul care generează blocurile YAML suplimentare pentru a fi rulate.

Pentru documentele cu cvarto folosind motorul KNITR, vinieta pachetului R arată cum să utilizați noul write_yaml_metadata_block() Funcționați într -o bucată de cod R cu tipul de ieșire asis Pentru a scrie blocul Yaml. În cazul în care este util pentru oricine, mai jos arăt exemple despre cum să scriu blocurile YAML în fiecare dintre celelalte trei motoare pe care le -am folosit.

Python (Jupyter: Python3)

```{python}
#| include: false
#| tags: (parameters)
solutions="true"
```

```{python}
#| include: false
from IPython.display import Markdown
ymltxt = f"  solutions: {solutions}"
if solutions == 'true':
    titletxt = "title: Solutions document"
else:
    titletxt = "title: Questions document"
```

`{python} Markdown("---")`
`{python} Markdown("params:")`
`{python} Markdown(ymltxt)`
`{python} Markdown(titletxt)`
`{python} Markdown("---")`

::: {.content-visible when-meta="params.solutions"}
```{python}
print("A solution, which is hidden in questions")
```
:::

Stata (Jupyter: NBSTATA)

```{stata}
*| include: false
local solutions : env SOLUTIONS_STATA
scalar ymltxt = "  solutions: `solutions'"
if "`solutions'" == "true" {
  scalar titletxt = "title: Solutions document"
}
else {
  scalar titletxt = "title: Questions document"
}
```

`{stata} "---"`
`{stata} "params:"`
`{stata} scalar(ymltxt)`
`{stata} scalar(titletxt)`
`{stata} "---"`

::: {.content-visible when-meta="params.solutions"}
```{stata}
display "A solution, which is hidden in questions"
```
:::

Julia (motor: Julia)

```{julia}
#| tags: (parameters)
```

```{julia}
#| echo: false
#| output: asis
println("---")
if solutions
  println("title: Solutions document")
  ymltxt = "  solutions: true"
else
  println("title: Questions document")
  ymltxt = "  solutions: false"
end
println("params:")
println(ymltxt)
println("---")
```

::: {.content-visible when-meta="params.solutions"}
```{julia}
println("A solution, hidden in questions")
```
:::

Rezumat

Am arătat cum să creez profiluri de quarto pentru crearea foilor de lucru pentru tutorial; una pentru întrebări și una pentru soluții din același document de cvarto; pentru mai multe motoare cu cvarto (engine: knitr, jupyter: python3, jupyter: nbstatași engine: julia) Am arătat, de asemenea, cum pot fi scrise metadate suplimentare în documentul dvs. Quarto în aceste motoare, care pot fi utilizate împreună cu documente parametrizate și conținut condiționat.