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 | - descriptionPath: Path to a markdown file that contains the description of the exercise. |
| 24 | - placeholderSourcePath: Path to a Q# file. It contains Q# code which is used as template code that helps the user to start implementing a solution. |
| 25 | - codePaths: Q# file paths. This code is not shown to the user but is built with the user code. Verification code in one of these files. The @EntryPoint operation is called to check the solution (eventually, for the convention is to call Kata.Verification.CheckSolution). |
| 26 | - solutionPath: Path to a markdown file that contains a “reference solution” – text with at least one code solution that solves the exercise. It can have more than one code solution. |
| 27 | - @[question]: Used to create theoretical/analytical questions that are not automatically verified. |
| 28 | - id: Unique identifier for the question. |
| 29 | - descriptionPath: Path a markdown file that contains the description of the question. |
| 30 | - answerPath: Path to a markdown file that contains an explanation of the answer – a text and possibly code samples that explains how to solve this problem. |
| 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 and Questions 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. |
| 44 | |