Further formatting fixes for Workbench conversion

carpentries-incubator · Nov 28, 2024 · 41414d1 · 41414d1
1 parent 1a88b94
commit 41414d1
Show file tree

Hide file tree

Showing 41 changed files with 283 additions and 198 deletions.
diff --git a/config.yaml b/config.yaml
@@ -64,7 +64,7 @@ contact: '[email protected]'
 # - another-learner.md
 
 # Order of episodes in your lesson
-episodes: 
+episodes:
 - 00-setting-the-scene.md
 - 10-section1-intro.md
 - 11-software-project.md
@@ -97,26 +97,26 @@ episodes:
 - 60-wrap-up.md
 
 # Information for Learners
-learners: 
+learners:
 - quiz.md
-- learner-setup.md
+- installation-instructions.md
 - common-issues.md
-- reference.md
-- vscode.md
 - software-architecture-extra.md
 - programming-paradigms.md
 - procedural-programming.md
 - functional-programming.md
 - object-oriented-programming.md
 - persistence.md
 - databases.md
+- vscode.md
+- reference.md
 
 # Information for Instructors
-instructors: 
+instructors:
 - instructor-notes.md
 
 # Learner Profiles
-profiles: 
+profiles:
 
 # Customisation ---------------------------------------------
 #

diff --git a/episodes/10-section1-intro.md b/episodes/10-section1-intro.md
@@ -1,7 +1,5 @@
 ---
 title: 'Section 1: Setting Up Environment For Collaborative Code Development'
-colour: '#fafac8'
-start: yes
 teaching: 10
 exercises: 0
 ---

diff --git a/episodes/11-software-project.md b/episodes/11-software-project.md
@@ -1,5 +1,5 @@
 ---
-title: Introduction to Our Software Project
+title: 1.1 Introduction to Our Software Project
 teaching: 20
 exercises: 10
 ---

diff --git a/episodes/12-virtual-environments.md b/episodes/12-virtual-environments.md
@@ -1,5 +1,5 @@
 ---
-title: Virtual Environments For Software Development
+title: 1.2 Virtual Environments For Software Development
 start: no
 teaching: 30
 exercises: 0

diff --git a/episodes/13-ides.md b/episodes/13-ides.md
@@ -1,5 +1,5 @@
 ---
-title: Integrated Software Development Environments
+title: 1.3 Integrated Software Development Environments
 start: no
 teaching: 25
 exercises: 10

diff --git a/episodes/14-collaboration-using-git.md b/episodes/14-collaboration-using-git.md
@@ -1,5 +1,5 @@
 ---
-title: Software Development Using Git and GitHub
+title: 1.4 Software Development Using Git and GitHub
 start: no
 teaching: 35
 exercises: 0

diff --git a/episodes/15-coding-conventions.md b/episodes/15-coding-conventions.md
@@ -1,6 +1,5 @@
 ---
-title: Python Code Style Conventions
-start: no
+title: 1.5 Python Code Style Conventions
 teaching: 20
 exercises: 20
 ---
@@ -29,7 +28,8 @@ to make sure that your code is consistently formatted and readable by yourself a
 
 > *"Any fool can write code that a computer can understand.
 > Good programmers write code that humans can understand."*  
-> - [Martin Fowler](https://en.wikiquote.org/wiki/Martin_Fowler), British software engineer, author and international speaker on software development
+> 
+> --- [Martin Fowler](https://en.wikiquote.org/wiki/Martin_Fowler), British software engineer, author and international speaker on software development
 
 ## Python Coding Style Guide
 

diff --git a/episodes/16-verifying-code-style-linters.md b/episodes/16-verifying-code-style-linters.md
@@ -1,6 +1,5 @@
 ---
-title: Verifying Code Style Using Linters
-start: no
+title: 1.6 Verifying Code Style Using Linters
 teaching: 15
 exercises: 5
 ---

diff --git a/episodes/17-section1-optional-exercises.md b/episodes/17-section1-optional-exercises.md
@@ -1,5 +1,5 @@
 ---
-title: Optional Exercises for Section 1
+title: 1.7 Optional Exercises for Section 1
 start: no
 teaching: 0
 exercises: 45

diff --git a/episodes/20-section2-intro.md b/episodes/20-section2-intro.md
@@ -1,7 +1,5 @@
 ---
 title: 'Section 2: Ensuring Correctness of Software at Scale'
-colour: '#fafac8'
-start: yes
 teaching: 5
 exercises: 0
 ---

diff --git a/episodes/21-automatically-testing-software.md b/episodes/21-automatically-testing-software.md
@@ -1,5 +1,5 @@
 ---
-title: Automatically Testing Software
+title: 2.1 Automatically Testing Software
 teaching: 30
 exercises: 15
 ---

diff --git a/episodes/22-scaling-up-unit-testing.md b/episodes/22-scaling-up-unit-testing.md
@@ -1,5 +1,5 @@
 ---
-title: Scaling Up Unit Testing
+title: 2.2 Scaling Up Unit Testing
 teaching: 10
 exercises: 5
 ---

diff --git a/episodes/23-continuous-integration-automated-testing.md b/episodes/23-continuous-integration-automated-testing.md
@@ -1,5 +1,5 @@
 ---
-title: Continuous Integration for Automated Testing
+title: 2.3 Continuous Integration for Automated Testing
 teaching: 45
 exercises: 0
 ---
@@ -366,7 +366,7 @@ jobs:
         python-version: ["3.10", "3.11"]
 
     # Here we add the reference to the os matrix values
-    runs-on: {% raw %}${{ matrix.os }}{% endraw %}
+    runs-on: ${{ matrix.os }}
 
     # Same key-value pairs as in "Defining Our Workflow" section
     steps:
@@ -378,7 +378,7 @@ jobs:
       uses: actions/setup-python@v5
       with:
         # Here we add the reference to the python-version matrix values
-        python-version: {% raw %}${{ matrix.python-version }}{% endraw %}
+        python-version: ${{ matrix.python-version }}
     # Same steps as in "Defining Our Workflow" section
     - name: Install Python dependencies
       run: |
@@ -389,7 +389,7 @@ jobs:
         python3 -m pytest --cov=catchment.models tests/test_models.py
 ```
 
-The `{% raw %}${{ }}{% endraw %}` are used
+The `{{ }}` are used
 as a means to reference configuration values from the matrix.
 This way, every possible permutation of Python versions 3.10 and 3.11
 with the latest versions of Ubuntu, Mac OS and Windows operating systems

diff --git a/episodes/24-diagnosing-issues-improving-robustness.md b/episodes/24-diagnosing-issues-improving-robustness.md
@@ -1,5 +1,5 @@
 ---
-title: Diagnosing Issues and Improving Robustness
+title: 2.4 Diagnosing Issues and Improving Robustness
 teaching: 30
 exercises: 15
 ---

diff --git a/episodes/25-section2-optional-exercises.md b/episodes/25-section2-optional-exercises.md
@@ -1,5 +1,5 @@
 ---
-title: Optional Exercises for Section 2
+title: 2.5 Optional Exercises for Section 2
 start: no
 teaching: 0
 exercises: 45

diff --git a/episodes/30-section3-intro.md b/episodes/30-section3-intro.md
@@ -1,7 +1,5 @@
 ---
 title: 'Section 3: Software Development as a Process'
-colour: '#fafac8'
-start: yes
 teaching: 10
 exercises: 0
 ---
@@ -23,7 +21,9 @@ exercises: 0
 In this section, we will take a step back from coding development practices and tools
 and look at the bigger picture of software as a *process* of development.
 
-> *"If you fail to plan, you are planning to fail."* - Benjamin Franklin
+> *"If you fail to plan, you are planning to fail."* 
+> 
+> --- Benjamin Franklin
 
 ![](fig/section3-overview.svg){alt='Software design and architecture overview flowchart'}
 

diff --git a/episodes/31-software-requirements.md b/episodes/31-software-requirements.md
@@ -1,5 +1,5 @@
 ---
-title: Software Requirements
+title: 3.1 Software Requirements
 teaching: 25
 exercises: 15
 ---

diff --git a/episodes/32-software-architecture-design.md b/episodes/32-software-architecture-design.md
@@ -1,5 +1,5 @@
 ---
-title: Software Architecture and Design
+title: 3.2 Software Architecture and Design
 teaching: 25
 exercises: 25
 ---

diff --git a/episodes/33-code-decoupling-abstractions.md b/episodes/33-code-decoupling-abstractions.md
@@ -1,5 +1,5 @@
 ---
-title: Code Decoupling & Abstractions
+title: 3.3 Code Decoupling & Abstractions
 teaching: 30
 exercises: 45
 ---

diff --git a/episodes/34-code-refactoring.md b/episodes/34-code-refactoring.md
@@ -1,5 +1,5 @@
 ---
-title: Code Refactoring
+title: 3.4 Code Refactoring
 teaching: 30
 exercises: 20
 ---

diff --git a/episodes/35-software-architecture-revisited.md b/episodes/35-software-architecture-revisited.md
@@ -1,5 +1,5 @@
 ---
-title: Software Architecture Revisited
+title: 3.5 Software Architecture Revisited
 teaching: 15
 exercises: 30
 ---

diff --git a/episodes/40-section4-intro.md b/episodes/40-section4-intro.md
@@ -1,7 +1,5 @@
 ---
 title: 'Section 4: Collaborative Software Development for Reuse'
-colour: '#fafac8'
-start: yes
 teaching: 5
 exercises: 0
 ---
@@ -48,46 +46,44 @@ using **Poetry** to manage our Python dependencies
 and produce a code package we can use with a Python package indexing service
 to illustrate these principles.
 
-{% comment %}
-![](fig/section4-overview.png){alt='Software design and architecture' .image-with-shadow width="800px" }
-{% endcomment %}
-
 ![](fig/section4-overview.svg){alt='Software design and architecture' .image-with-shadow width="1000px" }
 
-{% comment %}
+<!--
+Source of the above image can be rendered in the Mermaid live editor:
+
+https://mermaid.live/edit#pako:eNpVkE9rwzAMxb-K8CmFNrB_lxwGW9vbellhh-GLlsitIZGCrKSU0u8-t2vYpouF9HsP-Z1cLQ25yoVWDvUe1eDt3fNLcVfClswi72DoPScJdkAlIB6jCnfENvO8WDzDa3FfwgdpDMdM_0FrUaXamFK6ocviIdtO-4ZGaqW_WHnGBAi9Sv1Lr4rHEpbStvglihZH8vxHA0EUlIaUx54h1wL-vzefdfFUwgYZd5ffTOd5lpEUoiVoYyCLHc3c3HWkHcYmJ3K6mHhne-rIuyq3DQUcWvPO8zmjOJhsj1y7ynSguRv6Bo1WEXeKnasCtilPqYkmuvlJ-Rr2RK6vm0ndI3-KTLrzNzfGi8o
+
+The mermaid source (with one less dash in arrows than needed):
+
 flowchart LR
 A(1. Setting up
 software environment)
-\--> B(2. Verifying
+-> B(2. Verifying
 software correctness)
-\--> C(3. Software development
+-> C(3. Software development
 as a process)
-\--> D(4. Collaborative
+-> D(4. Collaborative
 development for reuse
 
-```
-- Code review
-- Software documentation
-- Software packaging & release
-)
-```
-
-\--> E(5. Managing software
+    - Code review
+    - Software documentation
+    - Software packaging & release
+    )
+-> E(5. Managing software
 over its lifetime)
 
-<https://mermaid.live/edit#pako:eNpVkE9rwzAMxb-K8CmFNrB_lxwGW9vbellhh-GLlsitIZGCrKSU0u8-t2vYpouF9HsP-Z1cLQ25yoVWDvUe1eDt3fNLcVfClswi72DoPScJdkAlIB6jCnfENvO8WDzDa3FfwgdpDMdM_0FrUaXamFK6ocviIdtO-4ZGaqW_WHnGBAi9Sv1Lr4rHEpbStvglihZH8vxHA0EUlIaUx54h1wL-vzefdfFUwgYZd5ffTOd5lpEUoiVoYyCLHc3c3HWkHcYmJ3K6mHhne-rIuyq3DQUcWvPO8zmjOJhsj1y7ynSguRv6Bo1WEXeKnasCtilPqYkmuvlJ-Rr2RK6vm0ndI3-KTLrzNzfGi8o>
-{% endcomment %}
+-->
 
 
 
-{% comment %}
+<!--
 Designing and Developing "Good" Software in Teams
 
 - **Software paradigms and design architectures** for solving different problems based on clear requirements
 - **Writing "good" software** that is understandable, modular, extensible and tested
 - **Publishing and releasing software** for reuse by others
 - **Collaborative code development and review** to improve software sustainability and avoid the accumulation of 'technical debt'.
-  {% endcomment %}
+-->
 
 :::::::::::::::::::::::::::::::::::::::: keypoints
 

diff --git a/episodes/41-code-review.md b/episodes/41-code-review.md
@@ -1,5 +1,5 @@
 ---
-title: 'Developing Software In a Team: Code Review'
+title: '4.1 Developing Software In a Team: Code Review'
 teaching: 30
 exercises: 30
 ---
@@ -181,7 +181,7 @@ have not seen before.
 
 Here is an outline of the process of a tool assisted code review.
 
-{% comment %}
+<!--
 
 ```mermaid
 %% Must disable useMaxWidth to have the diagram centre
@@ -202,7 +202,8 @@ sequenceDiagram
 ```
 
 Generated with Mermaid tool, diagram available at: <https://mermaid.live/edit#pako:eNptUrtuwzAM_BVCgOEl_QEPAYx29eKgyOKFsZhYgF6VKLeBkX-vXDvNo5UWSXfHI0VOoneSRCWKApoUGaSKeNAEKVKDX3sleQB2MOBIwANlHE8BDfRkOVBni2JSVnEFE5SRPhLZnsp8K-8ClNURdaQL5F0Unb3y3pZYnYW8PAZWvfJoGWrACHXiwYW_YDuDLY2KPmmF65fttq5gHxQTRGcI5qpuWFtBiyoSIPikNYQ5gcgLoV0ItZRZZUyuK84VY2bNHjdSdtilg1H8hGnnPLxbVhrQ--BGkgtwZ5-jB4oRXMjS6J2Vs8cS5df2plrtXjUGdTyvKqdHeuKSlQ_51Yv_P1WuX9RQOD3CYiMMBYNK5imYZnIncqMNdaLKR0lHTJo70dlLpmJitzvbXlQcEm1E8hL52sjrI0nFLjTLYP3M1-Ub_pDLrQ>
-{% endcomment %}
+-->
+
 ![](fig/code-review-sequence-diagram.svg){alt='Code review process sequence' .image-with-shadow width="600px"}
 
 Recall [solution requirement SR1.1.1](31-software-requirements.md)

diff --git a/episodes/42-software-reuse.md b/episodes/42-software-reuse.md
@@ -1,5 +1,5 @@
 ---
-title: Preparing Software for Reuse and Release
+title: 4.2 Preparing Software for Reuse and Release
 start: no
 teaching: 35
 exercises: 15

diff --git a/episodes/43-software-release.md b/episodes/43-software-release.md
@@ -1,5 +1,5 @@
 ---
-title: Packaging Code for Release and Distribution
+title: 4.3 Packaging Code for Release and Distribution
 teaching: 0
 exercises: 20
 ---