GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/qdk

Public

mirrored fromhttps://github.com/microsoft/qdkAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
c2d2246f04df6a928da5b851b624123e4cc719da

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

qdk/katas

katas/README.md

130lines · modecode

RawDownload
Latest commit unavailable.
1# Katas
2
3A 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
5- Lessons: text content that sometimes contains Q# code examples.
6- Exercises: problems that the user solves by writting Q# code.
7- Questions: analytical problems that have a text answer.
8
9## Run Katas Online
10
11Visit [Learn with Microsoft Quantum katas](https://quantum.microsoft.com/experience/quantum-katas) to try the new online Microsoft Quantum katas experience, with integrated assistance from Copilot in Microsoft Quantum.
12
13## Build Katas Locally
14
15We need to build the `playground` module to see the built katas locally. For the detailed instructions, refer to [Building Playground Locally](../source/playground/README.md#building-the-playground-locally).
16
17## Rust crate
18
19The katas crate exposes an API to check solutions for exercises.
20
21## Composition
22
23Katas are composed through an index.md markdown file that uses macros to indicate how to produce content for different kinds of sections.
24
25### Macros
26
27Macros 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`.
28
29The following macros are available for katas composition:
30
31- @[exercise]: Used to create Q# code exercises that we can be automatically verified.
32 - id: Unique identifier for the exercise.
33 - title: Title that will be displayed for the exercise.
34 - path: Path to a folder that contains the description of the exercise. This folder should contain the following files:
35 - `index.md`: the Markdown description of the exercise.
36 - `Placeholder.qs`: the Q# code that is given to the learner to start with.
37 - `Verification.qs`: the Q# code that checks whether the learner's solution is correct.
38 - `solution.md`: the Markdown description of the solution(s) to the exercise.
39 - `Solution.qs`: the Q# code that contains a "reference solution" described in `solution.md`.
40 The @EntryPoint operation is called to check the solution (eventually, for the convention is to call Kata.Verification.CheckSolution).
41- @[example]: Standalone Q# code snippets that can be referenced from markdown files.
42 - id: Unique identifier for the example.
43 - codePath: Path to a Q# file that contains the example code.
44- @[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.
45 - id: Unique identifier for the solution.
46 - codePath: Path to a Q# file that contains the solution code.
47- @[section]: A kata is broken into multiple sections. This starts a new section. Exercises are their own sections.
48 - id: Unique identifier for the section.
49 - title: Title of the section.
50
51### Images
52
53Constructing SVG images correctly for the katas is a little involved due to the need to support dark
54and light themes on QCOM. Currently this follows the OS preference, but it is also common to allow the
55theme to be set via a `data-theme` attribute on a parent element, (e.g., the playground does this to force
56light mode, as it doesn't support other themes currently).
57
58To support this, CSS needs to be used. However if the CSS is not contained within the image itself, then
59editing or previewing the SVG file becomes very awkward. Therefore the approach taken is that the CSS
60be included directly in each image. The below CSS should be pasted directly into each `.svg` file used
61in the katas, directly after the opening `<svg>` element.
62
63IMPORTANT: As the SVG file becomes inline HTML in Markdown, it is important that there are no blank lines
64within the .svg files anywhere (including the CSS block), due to the way Markdown parsers determine
65a block of HTML has terminated. The kata generation script checks for this and will fail if any exist.
66
67```html
68<style>
69/* Default values, or theme set explicitly to light */
70:root, [data-theme="light"] {
71 --kata-svg-stroke: #222;
72 --kata-svg-fill: #fff;
73 --kata-svg-path: #777;
74 --kata-svg-accent: #06c;
75}
76/* User has set OS preference for dark. (An explict light theme will override) */
77@media(prefers-color-scheme: dark) {
78 :root {
79 --kata-svg-stroke: #eee;
80 --kata-svg-fill: #111;
81 --kata-svg-path: #bbb;
82 --kata-svg-accent: #08f;
83 }
84}
85/* Explicit dark theme set (should match above dark preference values) */
86[data-theme="dark"] {
87 --kata-svg-stroke: #eee;
88 --kata-svg-fill: #111;
89 --kata-svg-path: #bbb;
90 --kata-svg-accent: #08f;
91}
92/*** Kata specific styles ***/
93.kata_svg_path {
94 stroke: var(--kata-svg-path);
95 stroke-width: 2;
96 stroke-linecap: round;
97 fill: none;
98}
99.kata_svg_text {
100 fill: var(--kata-svg-stroke);
101}
102.kata_svg_point {
103 fill: var(--kata-svg-fill);
104 stroke: var(--kata-svg-stroke);
105}
106.kata_svg_fill_accent {
107 fill: var(--kata-svg-accent);
108}
109.kata_svg_stroke_accent {
110 stroke: var(--kata-svg-accent);
111}
112</style>
113```
114
115For previewing how each SVG image will look, and for making manual tweaks to the SVG markup (which is
116similar to HTML), I recommend the VS Code extension at <https://marketplace.visualstudio.com/items?itemName=jock.svg>.
117With this installed in VS Code, you can right-click on an SVG file and select 'Preview SVG'. The CSS takes
118effect, so changing the OS theme will change how the preview appears. (Note: You can choose a different background
119color from the swatch at the top of the preview. I recommend the first swatch option of "Use editor background", and then enable the VS Code setting `Window: Auto-detect color scheme`. That way as you change OS theme, the VS Code preview will match).
120
121For more involved SVG editing I recommend Inkscape (<https://inkscape.org/>), however it has a bit of
122learning curve, and doesn't handle custom CSS properties very well, so the below CSS may need to be
123modified before working in Inkscape, then replaced again after the image changes have been saved.
124
125If not familiar with the SVG format, the MDN reference at <https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial>
126provides a very good overview.
127
128## Acknowledgements
129
130Content 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.
131