Workshop Content (#1)

* Workshop exercises and notes outline

* Prereqs

* Exercises

* Quarto book

* Linked files not rendering (bug)

* Content review

* Pages still not rendering (bug)

.github/workflows/deploy.yml

@@ -0,0 +1,69 @@
+
+name: deploy
+
+on:
+  push:
+    branches:
+    - main
+
+  # make this workflow manually runnable
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch
+  workflow_dispatch:
+
+
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+
+    #
+    # PYTHON STUFF
+    #
+
+    # INSTALL PYTHON
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+
+    ## INSTALL DOCUMENTATION DEPENDENCIES
+    #- name: Install docs dependencies
+    #  run: |
+    #    pip install -r docs/requirements.txt
+
+    #
+    # QUARTO STUFF
+    #
+
+    # INSTALL QUARTO
+    - name: Set up Quarto
+      uses: quarto-dev/quarto-actions/setup@v2
+      with:
+        # Install LaTeX to build PDF book (to make the build pass)
+        tinytex: true
+        # optionally pin a version:
+        # version: pre-release
+
+    # RENDER HTML AND PDF (see docs/_build)
+    - name: Build the book
+      run: |
+        quarto render docs/
+
+    #
+    # GITHUB PAGES STUFF
+    #
+
+    # Upload the book's HTML as an artifact
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: "docs/_build"
+
+    # Deploy the book's HTML to GitHub Pages
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,7 @@
+
+
+.DS_Store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

Makefile

@@ -0,0 +1,23 @@
+
+preview:
+	quarto preview docs/
+
+render:
+	quarto render docs/
+
+build:
+	quarto render docs/
+	open docs/_build/index.html
+
+open:
+	open docs/_build/index.html
+
+#open-pdf:
+#	open docs/_build/index.pdf
+
+
+# remove cache to get a clean build, as desired:
+render-fresh:
+	rm -rf docs/_build
+	rf -rf docs/.quarto
+	quarto render docs/

README.md

@@ -5,18 +5,16 @@
 **Description:** Install and configure tools to help you manage and develop Python programs like a professional. Attendees will become familiar with development tools such as a text editor and command line application.
 
 **Learning Objectives:**
-1. Use GitHub Desktop software to download existing Python repositories from GitHub.
-2. Utilize local development tools to write and execute Python code for research and software development.
+1. Utilize local development tools to write and execute Python code for research and software development.
+2. Use GitHub Desktop software to download existing Python repositories from GitHub.
 3. Use a text editor to read, write, and save files of Python code.
 4. Create and manage virtual environments using Anaconda.
-5. Manage package installations effectively using pip within a virtual environment
-2. use a requirements file to list package dependencies for a given project.
-6. Discuss security measures needed to protect secret credentials used by research and application code.
-7. Run Python programs on your computer.
+5. Manage package installations effectively using Pip within a virtual environment, and practice using a requirements file to list package dependencies for a given project.
+6. Run Python programs on your computer.
+7. Discuss security measures needed to protect secret credentials used by research and application code.
 
 **Required Software:**
 + GitHub Desktop (requires a GitHub account)
 + VS Code Text Editor
-+ Anaconda
++ Anaconda, Python, and Pip
 + Command Line Application (Terminal on Mac, Git Bash on Windows)
-

docs/.gitignore

@@ -0,0 +1 @@
+/.quarto/

docs/_quarto.yml

@@ -0,0 +1,131 @@
+project:
+  type: book # website
+  output-dir: "_build"
+  preview:
+    port: 4567
+    browser: true
+
+
+  render:
+    # be able to link to these other hidden documents not included in the sidebar contents
+    # (this doesn't work though???)
+    # https://quarto.org/docs/projects/quarto-projects.html#render-targets
+    # https://github.com/quarto-dev/quarto-cli/discussions/7312#discussioncomment-7345228
+    - prereqs/local-dev-setup/terminal-config.qmd
+    - prereqs/local-dev-setup/vs-code-config.qmd
+    - exercises/run-the-app/troubleshooting.qmd
+    - notes/clis/brew.qmd
+
+
+# https://quarto.org/docs/books/
+# https://quarto.org/docs/reference/projects/books.html
+book:
+  title: "Local Development Tools for Python Programming"
+  author: "Michael Rossetti"
+  date: "last-modified" # "7/24/2024"
+  date-format: "iso"
+  #doi: "...."
+  #isbn: "..."
+  #issn: "..."
+  #edition: "v2"
+
+#website:
+
+  site-url: https://s2t2.github.io/python-dev-tools-workshop-2024/
+  repo-url: https://github.com/s2t2/python-dev-tools-workshop-2024
+  repo-branch: main
+  repo-subdir: docs
+  repo-actions: [edit, issue, source]
+  #downloads: [pdf, epub, docx]
+
+  # https://quarto.org/docs/websites/website-tools.html#google-analytics
+  #google-analytics: "G-..."
+
+  #sharing: [twitter, facebook]
+  # https://quarto.org/docs/websites/website-tools.html#open-graph
+  open-graph: true
+
+  # https://quarto.org/docs/reference/projects/books.html#search
+  search: true
+    #location: sidebar # navbar, sidebar
+    #type: textbox # overlay, textbox
+
+  #cover-image: images/cover.png
+  #favicon: images/favicon.ico
+
+  # https://quarto.org/docs/websites/website-navigation.html#side-navigation
+  #sidebar:
+  #  logo: images/ospo-logo.png
+
+  #sidebar:
+  #  contents:
+  #    - index.qmd
+  #
+  #    - section:
+  #      href: prereqs/local-dev-setup/index.qmd
+  #      title: "Prerequisites"
+  #      contents:
+  #        - prereqs/local-dev-setup/github.qmd
+  #        - prereqs/local-dev-setup/vs-code-text-editor.qmd
+  #        - prereqs/local-dev-setup/terminal.qmd
+  #        - prereqs/local-dev-setup/anaconda.qmd
+  #        - prereqs/local-dev-setup/git-client.qmd
+
+
+  chapters:
+    - index.qmd
+
+    - "-------------"
+
+    - part: "Setup Guide (Prereqs)"
+      href: prereqs/local-dev-setup/index.qmd
+      chapters:
+        - prereqs/local-dev-setup/github.qmd
+        - prereqs/local-dev-setup/vs-code-text-editor.qmd
+        - prereqs/local-dev-setup/terminal.qmd
+        - prereqs/local-dev-setup/anaconda.qmd
+        - prereqs/local-dev-setup/git-client.qmd
+
+
+
+    - "-------------"
+
+    - part: "Workshop Exercises"
+      chapters:
+        - href: exercises/command-line-computing/index.qmd
+          text: Command-line Computing
+        - href: exercises/hello-python/index.qmd
+          text: Hello Python
+        - href: exercises/run-the-app/index.qmd
+          text: Run the App (Tic Tac Toe)
+
+
+    - "-------------"
+
+
+  #appendices:
+
+
+  # shows up at bottom of page
+  #body-footer: "© Copyright 2024, Your Name Here"
+
+  #page-footer:
+  #  center: |
+  #    <p>&copy; Copyright 2024, GWU Open Source Program Office (OSPO)</p>
+
+
+#bibliography: references.bib
+
+format:
+  html:
+    # https://quarto.org/docs/output-formats/html-themes.html
+    theme:
+      light: default #flatly
+      dark: darkly
+    css: styles.css
+    number-sections: false
+    from: markdown+emoji # enable emojis
+
+
+  #pdf:
+  #  documentclass: scrreprt