microsoft/qdk
Publicmirrored fromhttps://github.com/microsoft/qdkAvailable
katas/README.md
43lines · modecode
| 1 | # Katas |
| 2 | |
| 3 | A Kata is a top-level container of educational items which are used to explain a particular quantum computing topic using Q#. They are organized in sections which can be of three types: |
| 4 | - Lessons: text content that sometimes contains Q# code examples. |
| 5 | - Exercises: problems that the user solves by writting Q# code. |
| 6 | - Questions: analytical problems that have a text answer. |
| 7 | |
| 8 | ## Rust crate |
| 9 | |
| 10 | The katas crate exposes an API to check solutions for exercises. |
| 11 | |
| 12 | ## Composition |
| 13 | |
| 14 | Katas are composed through an index.md markdown file that uses macros to indicate how to produce content for different kinds of sections. |
| 15 | |
| 16 | ### Macros |
| 17 | |
| 18 | Macros are meant to insert interactive elements into the content defined through markdown. A macro starts with the `@` character followed by a word inside square brackets where the word represents the name of the macro (e.g. `@[example]`). This is followed by a JSON string enclosed within parenthesis `({...})` where the JSON string represents the properties of the macro that determine the interactive content. The macro is terminated by a line break `\r?\n`. |
| 19 | |
| 20 | The following macros are available for katas composition: |
| 21 | - @[exercise]: Used to create Q# code exercises that we can be automatically verified. |
| 22 | - id: Unique identifier for the exercise. |
| 23 | - title: Title that will be displayed for the exercise. |
| 24 | - path: Path to a folder that contains the description of the exercise. This folder should contain the following files: |
| 25 | - `index.md`: the Markdown description of the exercise. |
| 26 | - `Placeholder.qs`: the Q# code that is given to the learner to start with. |
| 27 | - `Verification.qs`: the Q# code that checks whether the learner's solution is correct. |
| 28 | - `solution.md`: the Markdown description of the solution(s) to the exercise. |
| 29 | - `Solution.qs`: the Q# code that contains a "reference solution" described in `solution.md`. |
| 30 | - qsDependencies: Q# file paths used in addition to `Verification.qs`. This code is not shown to the learner but is used to build the learner's code. The @EntryPoint operation is called to check the solution (eventually, for the convention is to call Kata.Verification.CheckSolution). |
| 31 | - @[example]: Standalone Q# code snippets that can be referenced from markdown files. |
| 32 | - id: Unique identifier for the example. |
| 33 | - codePath: Path to a Q# file that contains the example code. |
| 34 | - @[solution]: represents a solution to a Q# code exercise. It is meant to be compiled as if it was the user authored code that solves a Q# code exercise. It can only be used in solution markdown files. |
| 35 | - id: Unique identifier for the solution. |
| 36 | - codePath: Path to a Q# file that contains the solution code. |
| 37 | - @[section]: A kata is broken into multiple sections. This starts a new section. Exercises are their own sections. |
| 38 | - id: Unique identifier for the section. |
| 39 | - title: Title of the section. |
| 40 | |
| 41 | ## Acknowledgements |
| 42 | |
| 43 | Content of these web-based katas is largely a port of the previous effort located in the [QuantumKatas](https://github.com/microsoft/QuantumKatas) repository. Please refer to that repository for a history of contributions. |