Course authoring guide for QDK Learning courses - #3655
Course authoring guide for QDK Learning courses#3655Dhairya Patel (HABER7789) wants to merge 5 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
Updates and adds documentation for authoring QDK Learning courses within the VS Code extension tree, and ensures the new authoring guide is excluded from the shipped extension package.
Changes:
- Add a new “Authoring a QDK Learning course” guide describing course layout,
course.json, exercise tagging, and validation. - Document environment/dependency setup and workflow tips for updating published courses.
- Exclude the new guide from VS Code extension packaging via
.vscodeignore.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| source/vscode/authoring-courses.md | New course authoring documentation (structure, metadata, exercises, validation, environment, and workflow). |
| source/vscode/.vscodeignore | Excludes the new authoring guide from the packaged extension. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| `_course_lib.py` and `_check_env.py` aren't supplied by the extension, so copy them from an existing course when starting a new one. | ||
|
|
||
| _Note_: The folders in this example are numbered, but that's not required - the order comes from `course.json` |
There was a problem hiding this comment.
| _Note_: The folders in this example are numbered, but that's not required - the order comes from `course.json` | |
| _Note_: The folders in this example are numbered, but that's not required - the display order comes from `course.json` |
There was a problem hiding this comment.
Applied your suggestions.
| - `requirements.txt` lists course dependencies; each unit's first cell has a commented-out `%pip install -r ../requirements.txt` for the learner to run | ||
| - The `QDK: Create a Microsoft Quantum Python virtual environment` command sets up an environment and prompts for the packages to install | ||
| - `course.json` lets you list imports you expect to work so they can be checked before the student starts the unit (e.g. in case they've selected the wrong notebook kernel), which the course's `_check_env.py` reads | ||
| - The course infrastructure depends on the Python and Jupyter VS Code extensions, so they'll be prompted if those are absent |
There was a problem hiding this comment.
Nit: I find "they" ambiguous here - consider "the learner"
There was a problem hiding this comment.
Fixed.
| ## Trying it out | ||
|
|
||
| Open a workspace folder in VS Code and navigate to the Microsoft Quantum extension panel (indicated by a Mobius strip). | ||
| If you've never used it before, it'll offer you a `Start Learning` button. |
There was a problem hiding this comment.
"To return to this state, you can delete qdk-learning.json" (with more details, probably)
There was a problem hiding this comment.
Applied it
|
|
||
| Open a workspace folder in VS Code and navigate to the Microsoft Quantum extension panel (indicated by a Mobius strip). | ||
| If you've never used it before, it'll offer you a `Start Learning` button. | ||
| The Microsoft Quantum Katas are the default course, so you'll need to explicitly Switch Course to your new content in the tree view. |
There was a problem hiding this comment.
Not as true as it used to be
There was a problem hiding this comment.
Dropped it, now it just says SwitchCourse.
|
|
||
| When you switch to your course, temporary working copies of all the notebooks will be created (indicated by the `.workbook.ipynb` file extension). | ||
| These copies omit all the exercise hints, solutions, and explanations and give the learner a notebook they can edit freely without worrying about overwriting anything important. | ||
| An existing working copy is never overwritten, so if you based your course on a sample you'd previously run, `git clean` it first to clear out any working copies left behind. |
There was a problem hiding this comment.
Personally, I find "never overwritten" too strong.
There was a problem hiding this comment.
Okay, changed it with "isn't replaced when the course is copied"
|
|
||
| When you switch to your course, temporary working copies of all the notebooks will be created (indicated by the `.workbook.ipynb` file extension). | ||
| These copies omit all the exercise hints, solutions, and explanations and give the learner a notebook they can edit freely without worrying about overwriting anything important. | ||
| An existing working copy is never overwritten, so if you based your course on a sample you'd previously run, `git clean` it first to clear out any working copies left behind. |
There was a problem hiding this comment.
git clean is a dangerous thing to recommend if you're not confident the author has their course files checked in.
There was a problem hiding this comment.
Oops, thanks for the catch. Instead mentioned about deleting the leftover *.workbook.ipynb files
Updates the previous course authoring guide to match the current codebase.