Merge pull request #52 from SissiFeng/main

update MD files for software dev course

docs/course-data.yaml

@@ -559,22 +559,39 @@ software-dev:
   course_assessments_and_grading_schema: "{{ courses.hello-world.course_assessments_and_grading_schema }}"
   developers:
     - "Sterling Baird, PhD Materials Science and Engineering (Acceleration Consortium)"
+    - "Sissi Feng, PhD Electrical and Computer Engineering (Acceleration Consortium)"
   module_note: "Each module is intended to take approximately 3-4 hours, assuming that the recommended prerequisites have been met."
   modules:
+    - module_name: "4.0 Orientation"
+      tutorial_file: 4.0-orientation.md
+      topics:
+        - "Git"
+        - "GitHub"
+        - "Version control"
+        - "GitHub Classroom"
+        - "Codespaces"
+      learning_outcomes:
+        - "Describe the purpose of Git and GitHub"
+        - "Create a GitHub account and a repository"
+        - "Commit, push, and pull changes"
+        - "Run a unit test and fix a simple Python function"
+        - "Define continuous integration"
     - module_name: "Deep dive into Git and GitHub"
+      tutorial_file: 4.1-github-deep-dive.md
       topics:
         - "GitHub issues"
         - "Pull requests"
         - "Collaborative coding"
         - "Branches"
         - "Merge conflicts"
-        - "Project management"
+        # - "Project management"
       learning_outcomes:
         - "Open a GitHub issue on a repository"
         - "Create a new branch"
         - "Merge a GitHub pull request"
         - "Resolve a merge conflict"
     - module_name: "Setting up VS Code"
+      tutorial_file: 4.2-vscode-setup.md
       topics:
         - "IDEs"
         - "Miniconda"
@@ -590,6 +607,7 @@ software-dev:
         - "Install Miniconda"
         - "Install VS Code extensions"
     - module_name: "Debugging in VS Code"
+      tutorial_file: 4.3-vscode-debugging.md
       topics:
         - "Print statements"
         - "Setting breakpoints"
@@ -605,6 +623,7 @@ software-dev:
         - "Use the debug console"
         - "Set up debug configurations"
     - module_name: "Unit testing"
+      tutorial_file: 4.4-unit-testing.md
       topics:
         - "pytest"
         - "Test result interpretation"
@@ -621,6 +640,7 @@ software-dev:
     # Linting and code formatting? (e.g., black, flake8, isort, etc., especially VS Code Extensions)
     # VS Code extensions? (e.g., Python, Jupyter, Git, etc.)
     - module_name: "Automated documentation"
+      tutorial_file: 4.5-automated-docs.md
       topics:
         - "Markdown"
         - "Documentation as code"
@@ -635,6 +655,7 @@ software-dev:
       tutorial:
         - "GitHub-flavored Markdown tutorial"
     - module_name: "Continuous integration (CI)"
+      tutorial_file: 4.6-continuous-integration.md
       topics:
         - "Continuous integration"
         - "GitHub actions"
@@ -645,6 +666,7 @@ software-dev:
         - "Set up a GitHub actions workflow"
         - "Run unit tests and documentation builds on GitHub actions"
     - module_name: "Project templates"
+      tutorial_file: 4.7-project-templates.md
       topics:
         - "PyScaffold"
         - "Cookiecutter"
@@ -659,6 +681,7 @@ software-dev:
         - "Publish a Python package to PyPI"
         - "Outline the key benefits of dependency management during software development"
     - module_name: "Launching a free cloud server"
+      tutorial_file: 4.8-cloud-server.md
       topics:
         - "Serverless computing"
         - "PythonAnywhere"
@@ -670,6 +693,7 @@ software-dev:
         - "Create a container"
         - "Deploy a materials discovery campaign on a cloud server"
     - module_name: "On-demand cloud simulations"
+      tutorial_file: 4.9-cloud-simulations.md
       topics:
         - "Cloud computing"
         - "Setting up an AWS account"

docs/courses/software-dev/4.0-orientation.md

@@ -4,3 +4,88 @@
 ```{contents}
 :depth: 3
 ```
+
+## 🔰 Getting Started
+
+First, open up the following quiz in Canvas that corresponds to your enrolled term.
+
+::::{tab-set}
+:sync-group: category
+
+:::{tab-item} Sp/Su 2024
+:sync: w2024
+
+[TBD]
+:::
+
+:::{tab-item} Sp/Su 2025
+:sync: sp2024
+
+[TBD]
+:::
+
+::::
+
+You will record your GitHub username and GitHub Classroom Student Identifier, which will be used later in the course. You can refer back to these quiz answers if you forget. See below for information on these two.
+
+### GitHub Account
+
+These courses are integrated with coding exercises via GitHub Classroom, so you will need to [create a GitHub account](https://github.com/join) if you don't already have one. Take note of your GitHub username since you will enter this as a quiz response.
+
+```{tip}
+Two typical naming conventions for GitHub usernames are as follows:
+- John H. Smith → `jhsmith`
+- Jane M. Doe → `jane-doe`
+
+If you already have a GitHub account and you have used it infrequently, you may consider [renaming your GitHub account](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username) to adhere to one of the conventions above. This is completely optional.
+```
+
+### GitHub Starter Tutorial
+
+```{warning}
+The student identifier that you choose on the next page **will appear only once** (e.g., `quirky-zebra`). Please record this somewhere safe and enter it into the corresponding Canvas quiz, since you will be using this at various points throughout the course. If you forget or lose your student identifier, please send a message to [sterling.baird@utoronto.ca](mailto:sterling.baird@utoronto.ca).
+```
+
+Click on the 🔗 [GitHub starter tutorial](https://classroom.github.com/a/g78UiC5K), ensure you're logged in to GitHub, link to a student identifier of your choice (write this down), and accept the assignment. See below for a walkthrough of this.
+
+<video width="700" height="394" controls>
+  <source src="../../_static/intro-gh-classroom-walkthrough.mp4" type="video/mp4">
+  Your browser does not support the video tag.
+</video>
+
+<!-- <iframe style="width: 700px; height: 394px; display: inline-block;" title="Video player for github-starter-tutorial-select-accept.mp4" data-media-type="video" src="/media_attachments_iframe/31726637?embedded=true&amp;type=video" allowfullscreen="allowfullscreen" allow="fullscreen" data-media-id="m-49uHHDJPuMSZGb2RheoEbnm8NtVvuFMV" data-mce-fragment="1"></iframe> -->
+
+```{margin}
+There is a pre-populated list of student identifiers, none of which have been claimed! You may choose any of these.
+```
+
+Use this tutorial to familiarize yourself with git and GitHub terminology, which you will be quizzed on later.
+
+## 📄 GitHub Classroom Assignment
+
+Now that you're familiar with basic git and GitHub terminology, we can show you how to use GitHub Classroom for an autograded assignment.
+
+👉 **Second step**: This time, you will use an interactive development environment (IDE) called "Codespaces", with compute resources provided by the Acceleration Consortium through the GitHub Education program. Similar to the format before, click on the new assignment link 🔗 [Intro to GitHub Classroom](https://classroom.github.com/a/3yCVzX6I), ensure you're logged in to GitHub, accept the assignment, click the "Open in Codespaces" button, and follow the directions in the README.md file. Spinning up a new Codespace may take a minute or two, and a preview of the README.md file will automatically open up after a few seconds. A number of dialogue boxes and messages will appear during the loading process. Ensure that you sign into GitHub; use of Copilot is optional. The URL in your browser should be of the form `https://<some-funny-phrase>-<unique-id>.github.dev/` which is autogenerated and distinct from your course ID. For example, your URL might be `https://fuzzy-space-spork-9wggxx444g6h7rxq.github.dev/`. You can try the assignment as many times as you like, and you will self-report your autograded score on the next page. See below for a complete walkthrough of these steps.
+
+<video width="700" height="394" controls>
+  <source src="../../_static/run-the-demo-walkthrough.mp4" type="video/mp4">
+  Your browser does not support the video tag.
+</video>
+
+<!-- <iframe style="width: 700px; height: 394px; display: inline-block;" title="autograding-codespaces-python-walkthrough.mp4" data-media-type="video" src="https://q.utoronto.ca/media_attachments_iframe/31726639?embedded=true&amp;type=video" allowfullscreen="allowfullscreen" allow="fullscreen" data-titletext="autograding-codespaces-python-walkthrough.mp4" data-media-id="m-4qfTw9UDxLo8XrZpxMwCLDoT16FfTikf"></iframe> -->
+
+Additional resources:
+
+- [How students complete assignments](https://youtu.be/ObaFRGp_Eko?si=JMxjdheVKVc3Zwr8)
+- [What is Codespaces?](https://youtu.be/sYJ3CHtT6WM)
+- [Student developer pack](https://education.github.com/pack)
+
+```{tip}
+If you're eligible, consider signing up for the [student developer pack](https://education.github.com/pack) so that **you can have free access to GitHub Copilot (and GitHub Copilot Chat)**, among other perks. **GitHub Copilot is also free for teachers**.
+
+If you're not eligible, you may consider a paid subscription (~$10 USD/month). It's kind of like having a personal coding assistant to bounce ideas off of and have it look at your code. At the same time, it can become a crutch, and there are still times where plain-old Google searches, reading stack overflow posts, and searching through a GitHub repository's issues and documentation is better. The Acceleration Consortium does not benefit from you signing up for GitHub Copilot, and it is not required for the completion of this course.
+```
+
+## 📄 Python Refresher Assignment
+
+Optionally, you may try out the [Python refresher assignment](https://classroom.github.com/a/oDMoonRK). This is ungraded.

docs/courses/software-dev/4.1-vscode-setup.md

@@ -0,0 +1,152 @@
+
+(4.1-setup-vscode)=
+# 🧩 4.1 Setting Up VS Code
+
+```{contents}
+:depth: 3
+```
+
+## 🔰 Tutorial
+
+In this module, you will learn how to set up VS Code and optimize it for Python development using tools like Miniconda, various extensions, and advanced features.
+
+1. Set up VS Code
+2. Install Miniconda for environment management
+3. Install key VS Code extensions for Python development
+4. Configure SSH for remote development
+5. Explore advanced tools such as Black formatter, Pylance, and GitHub Copilot Chat
+
+### Setting Up VS Code
+
+First, you will download and install Visual Studio Code (VS Code), a lightweight and powerful editor. Then, you'll learn how to configure it for efficient Python development.
+
+#### Steps:
+
+1. Download and install VS Code from the official site: [VS Code Download](https://code.visualstudio.com/).
+2. Open VS Code and get familiar with the interface, including the command palette, sidebar, and settings menu.
+
+**Video Tutorial**: [Getting Started with VS Code](https://www.youtube.com/watch?v=VqCgcpAypFQ)
+
+### Installing Miniconda
+
+Miniconda is a lightweight distribution of Conda, an environment and package manager for Python. It allows you to manage multiple isolated environments on your machine.
+
+```{note}
+Consider using [Mamba](https://github.com/mamba-org/mamba), a widely used, fast (written in C++), drop-in replacement for conda.
+```
+
+#### Steps:
+
+1. Download Miniconda from the [official site](https://docs.conda.io/en/latest/miniconda.html).
+2. Install Miniconda by following the instructions for your operating system.
+3. After installation, create a new Python environment:
+   ```bash
+   conda create -n myenv python=3.9
+   conda activate myenv
+   ```
+
+4. Ensure that VS Code is set up to use this environment for Python development.
+
+**Video Tutorial**: [How to Install Miniconda](https://www.youtube.com/watch?v=oHHbsMfyNR4&pp=ygUYSG93IHRvIEluc3RhbGwgTWluaWNvbmRh)
+
+### Installing Essential VS Code Extensions
+
+Extensions can enhance the functionality of VS Code, especially for Python development. Below are some essential extensions to install:
+
+- [Python Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python): Adds Python language support.
+- [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance): A high-performance language server with type checking and autocompletion.
+- [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter): Automatically formats your Python code.
+- [autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring): Generates docstrings for your Python functions and methods.
+- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot): An AI-powered coding assistant.
+- [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat): AI chat features powered by Copilot.
+- [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh): For remote development using SSH.
+
+To install these extensions:
+1. Open the **Extensions** view in VS Code (`Ctrl + Shift + X`).
+2. Search for each extension by name and click **Install**.
+
+**Video Tutorial**: [Best VS Code Extensions for Python](https://www.youtube.com/watch?v=fj2tuTIcUys&pp=ygUiQmVzdCBWUyBDb2RlIEV4dGVuc2lvbnMgZm9yIFB5dGhvbg%3D%3D)
+
+### Using SSH for Remote Development
+
+VS Code supports remote development, allowing you to write and run code on a remote machine as if it were local.
+
+#### Steps:
+
+1. Install the **Remote - SSH** extension from the marketplace.
+2. Set up SSH on your local machine by generating SSH keys:
+   ```bash
+   ssh-keygen -t rsa -b 4096
+   ```
+3. Copy the public key to your remote server:
+   ```bash
+   ssh-copy-id username@hostname
+   ```
+4. Use VS Code's Remote Explorer to connect to the remote server using SSH.
+
+**Video Tutorial**: [VS Code Remote Development with SSH](https://www.youtube.com/watch?v=miyD4c1dnTU&pp=ygUjVlMgQ29kZSBSZW1vdGUgRGV2ZWxvcG1lbnQgd2l0aCBTU0g%3D)
+
+### Configuring Black Formatter
+
+Black is an opinionated Python code formatter that ensures code is formatted consistently. Here’s how to configure it in VS Code:
+
+1. Open the VS Code **Settings** (`Ctrl + ,`).
+2. Search for `Python Formatting Provider` and set it to `Black`.
+3. You can also configure VS Code to format your code on save by enabling the "Format on Save" option in settings.
+
+**Video Tutorial**: [How to Use Black in VS Code](https://www.youtube.com/watch?v=esZLCuWs_2Y)
+
+### GitHub Copilot Chat
+
+GitHub Copilot can assist you by suggesting code snippets, entire functions, and even refactoring your code. With **GitHub Copilot Chat**, you can interact with Copilot via a chat interface to get suggestions and resolve issues.
+
+#### Steps:
+
+1. Install **GitHub Copilot** and **GitHub Copilot Chat** extensions.
+2. After installation, sign in to your GitHub account in VS Code.
+3. Open the Copilot Chat interface and ask for help with coding, debugging, or writing functions.
+
+**Video Tutorial**: [GitHub Copilot Chat](https://www.youtube.com/watch?v=a2DDYMEPwbE&pp=ygUTR2l0SHViIENvcGlsb3QgQ2hhdA%3D%3D)
+
+### Additional Resources
+
+- [VS Code Documentation](https://code.visualstudio.com/docs)
+- [Conda Environments Guide](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
+- [Setting up VS Code for Python](https://code.visualstudio.com/docs/python/python-tutorial)
+- [Black Formatter Documentation](https://black.readthedocs.io/en/stable/)
+- [GitHub Copilot Documentation](https://docs.github.com/en/copilot)
+
+## 🚀 Quiz
+
+::::{tab-set}
+:sync-group: category
+
+:::{tab-item} Sp/Su 2024
+:sync: sp2024
+
+[URL]
+:::
+
+::::
+
+## 📄 Assignment
+
+1. **Set up VS Code**:
+   - Download and install VS Code, and create a Python virtual environment using Miniconda.
+
+2. **Install Extensions**:
+   - Install the recommended extensions and configure Black as the default formatter.
+
+3. **SSH Configuration**:
+   - Set up SSH access to a remote machine and use VS Code to write and run Python code remotely.
+
+::::{tab-set}
+:sync-group: category
+
+:::{tab-item} Sp/Su 2024
+:sync: sp2024
+
+[URL]
+:::
+
+::::