.. SPDX-FileCopyrightText: 2025 Xavier Bordoy <somenxavier@posteo.net>
..
.. SPDX-License-Identifier: CC-BY-SA-4.0

Usage
#########

wk.py
======

The basic way to use the program :download:`wk.py <../src/wk.py>` is

::

   python wk.py template exercise.md [options]

where:

- ``exercise.md`` is a markdown file with YAML headers which represent an exercise
- ``template`` is the Jinja template to use which gives the evaluation of the exercise and treats to create a document.

Exercises and templates are related in the sense that their need to use the same syntax (LaTeX, ConTeXt, typst, etc.).

For example, if you want to create an exercise to sum two random numbers between 1 and 100, assuming you want to generate a LaTeX
document, the exercise could be:

::

   ---
   parameters:
      a: random.randint(1,100)
      b: random.randint(1, 100)
   solution: |
      The solution is $ {{ params['a'] + params['b'] }} $.
   ---

   What is ${{params['a']}} + {{params['b']}}$?


and the template:

::

   \documentclass{article}
   \usepackage{amsmath}
   \usepackage{hyperref}
   \title{Worksheet}
   \author{Karl Kronecker}

   \begin{document}
   \maketitle

   \section{Exercises}

   \begin{enumerate}
   {% for e in exercises %}
     \item\label{ {{e.id}} } {{e.text}}
   {% endfor %}
   \end{enumerate}

   \newpage
   \section{Solutions}

   \begin{enumerate}
   {% for e in exercises %}
     \item[\ref{ {{e.id}} }.] {{e.solution}}
   {% endfor %}
   \end{enumerate}

   \end{document}


The result of previous command line is:

::

    \documentclass{article}
    \usepackage{amsmath}
    \usepackage{hyperref}
    \title{Worksheet}
    \author{Karl Kronecker}

    \begin{document}
    \maketitle

    \section{Exercises}

    \begin{enumerate}
      \item\label{ 73f3b975a451cffa435a212a67995b66646c62f776626eed18da9b55c8dda458 } What is $57 + 76$?
    \end{enumerate}

    \newpage
    \section{Solutions}

    \begin{enumerate}
      \item[\ref{ 73f3b975a451cffa435a212a67995b66646c62f776626eed18da9b55c8dda458 }.] The solution is $ 133 $.

    \end{enumerate}

    \end{document}


After that, you can compile as LaTeX document (with pdflatex for example). See :doc:`/docs/tutorial` for step-by-step reasoning.