Starting material

README.md

@@ -1,6 +1,4 @@
-# A template jupyter book documentation repository
-
-This is a template repository that can be used when generating documentation using [Jupyter-books](https://github.com/executablebooks/jupyter-book) and hosting the site via GitHub pages.
+# SWD3 Course Material
 
 ## Working with this project locally
 
@@ -20,14 +18,16 @@ $ cd template-jb-docs
 # sometimes worth running jupyter-book clean book/ to remove old files
 $ jupyter-book build book/
 ```
+
 ### Windows
 
 Jupyterbook now supports [Windows](https://jupyterbook.org/en/stable/advanced/windows.html) although the steps for configuring a development environment using Vagrant are available below:
 
 #### Set up a development environment using Vagrant
 
 To aid with this we have created a `Vagrantfile` that can allow Windows users who have a virtualisation provider installed (such as [VirtualBox](https://www.virtualbox.org/)) and [Vagrant](https://www.vagrantup.com/) installed to create a headless virtual Linux machine that will build the jupyter book. You can do this with the following steps once you've installed a virtualisation provider and vagrant:
-```
+
+```{bash}
 # within git-bash or powershell
 $ cd template-jb-docs
 $ vagrant up
@@ -39,4 +39,4 @@ $ vagrant reload --provision
 $ vagrant destroy
 ```
 
-This will build the jupyter-book html files on your Windows file system (by navigating via /vagrant) so your local build will still persist after you've destroyed your vagrant box.
+This will build the jupyter-book html files on your Windows file system (by navigating via /vagrant) so your local build will still persist after you've destroyed your vagrant box.

book/_config.yml

@@ -1,5 +1,5 @@
 # Book settings
-title: Template documentation jupyter book
+title: "SWD3: Software development practices for Research"
 author: University of Leeds Research Computing Team
 logo: ./assets/img/logo/logo.png
 email: [email protected]
@@ -14,7 +14,7 @@ html:
   favicon                   : "./assets/img/logo/favicon-32x32.png"  # A path to a favicon image
   navbar_number_sections    : False  # Add a number to each section in your left navbar
   google_analytics_id       : ""  # A GA id that can be used to track book views.
-  home_page_in_navbar       : true  # Whether to include your home page in the left Navigation Bar
+  home_page_in_navbar       : false  # Whether to include your home page in the left Navigation Bar
   use_repository_button: true
   use_issues_button: true
   use_edit_page_button: true

book/_toc.yml

@@ -6,8 +6,21 @@ root: welcome
 
 # ===== Getting started ==========================================
 sections:
-- file: example_section/start
-  sections:
-    - file: example_section/example
+
+- file: sections/setup
+- file: sections/lifecycle
+- file: sections/agile
+- file: sections/structure
+- file: sections/package-manager
+- file: sections/ide
+- file: sections/lint
+- file: sections/git
+- file: sections/testing
+- file: sections/tdd
+- file: sections/pytest
+- file: sections/unit
+- file: sections/study-case
+
+# ===== Footnote =================================================
 - url: https://arc.leeds.ac.uk
   title: Research Computing Website

book/sections/agile.md

@@ -0,0 +1,87 @@
+# Project management methodologies
+
+## Why choose a project management  methodology?
+
+> Without a design approach, programmers resort to designing as we go, typing in
+> code, trying what works, and making it up as we go along. When trying to
+> collaborate to make software with others this can result in lots of wasted
+> time, software that only the author understands, components built by
+> colleagues that don’t work together, or code that the programmer thinks is
+> nice but that doesn’t meet the user’s requirements.
+
+\- [The Alan Turing Institute](https://alan-turing-institute.github.io/rse-course/html/module06_software_projects/06_06_software_development.html#why-waterfall)
+
+## Traditional versus Agile
+
+> The traditional approach (Waterfall) argues that the elements of design should
+> occur in order: first requirements capture, then functional design, then
+> architectural design. This approach is based on the idea that if a mistake is
+> made in the design, then programming effort is wasted, so **significant effort
+> is spent in trying to ensure that requirements are well understood and that
+> the design is correct before programming starts**.
+
+\- [The Alan Turing Institute](https://alan-turing-institute.github.io/rse-course/html/module06_software_projects/06_06_software_development.html#waterfall)
+
+> Agile project management is an iterative approach to delivering a project
+> throughout its life cycle. Iterative or agile life cycles are composed of
+> several iterations or incremental steps towards the completion of a project.
+> Iterative approaches are frequently used in software development projects to
+> promote velocity and adaptability since the benefit of iteration is that you
+> can adjust as you go along rather than following a linear path. One of the
+> aims of an agile or iterative approach is to release benefits throughout the
+> process rather than only at the end.
+
+\- [Association for Project Management (APM)](https://www.apm.org.uk/resources/find-a-resource/agile-project-management/?gclid=CjwKCAiAgbiQBhAHEiwAuQ6Bkh-wsdy67h4_Ajehlwh3BGK2sPrcHP9tHXYwxrn7ReKjdT8LpOeyORoC_sEQAvD_BwE)
+
+![Traditional x Agile chart](https://www.apm.org.uk/media/40973/what-is-agile-project-management.png?width=1049&height=525)
+
+\- Figure from [Association for Project Management](https://www.apm.org.uk/)
+
+## The Agile Manifesto
+
+> We are uncovering better ways of developing software by doing it and helping
+> others do it.
+
+The Agile principles:
+
+- **Individuals and interactions** over processes and tools
+- **Working software** over comprehensive documentation
+- **Customer collaboration** over contract negotiation
+- **Responding to change** over following a plan
+
+\- [Manifesto for Agile Software Development](http://agilemanifesto.org/)
+
+```{admonition} Agile is not absence of methodology
+:class: warning
+The Agile movement is not anti-methodology, in fact, many of us want to restore credibility to the word methodology. We want to restore a balance. We embrace modelling, but not in order to file some diagram in a dusty corporate repository. We embrace documentation, but not hundreds of pages of never-maintained and rarely-used tomes. We plan, but recognize the limits of planning in a turbulent environment.
+
+\- Jim Highsmith from [The Alan Turing Institute](https://alan-turing-institute.github.io/rse-course/html/module06_software_projects/06_06_software_development.html#agile-is-not-absence-of-process)
+```
+
+```{seealso}
+[Twelve Principles Behind the Agile Manifesto](http://agilemanifesto.org/principles.html)
+```
+
+## Elements of an Agile Process
+
+- Ongoing design
+- Iterative development
+- Continuous delivery
+- Self-organising teams
+
+## Agile methodologies
+
+There are several methodologies that can be used to manage an agile project,
+including:
+
+- DAD (disciplined agile delivery)
+- DSDM (dynamic systems development method)
+- Kanban
+- Lean
+- LeSS (large-scale Scrum)
+- RAD (rapid application development)
+- SAFe (scaled agile framework enterprise)
+- Scaled agile
+- Scrum
+- Scrum of scrums
+- XP (eXtreme Programming)

book/sections/git.md

@@ -0,0 +1,87 @@
+# Version Control
+
+What is Version Control and why do I need it?
+
+## The problem
+
+Unfortunately the situation below is more common than we like to admit.
+
+[![Piled Higher and Deeper by Jorge Cham, http://www.phdcomics.com/comics/archive_print.php?comicid=1531](../assets/img/sections/phd101212s.png)](http://www.phdcomics.com)
+
+\- "Piled Higher and Deeper" by Jorge Cham, <http://www.phdcomics.com>
+
+It seems ridiculous to have multiple nearly-identical versions of the same
+document. Some word processors let us deal with this a little better, such as:
+
+- Microsoft Word's [Track Changes](https://support.office.com/en-us/article/Track-changes-in-Word-197ba630-0f5f-4a8e-9a77-3712475e806a)
+- Google Docs' [version history](https://support.google.com/docs/answer/190843?hl=en)
+- LibreOffice's [Recording and Displaying Changes](https://help.libreoffice.org/Common/Recording_and_Displaying_Changes).
+
+## The solution
+
+**Version control** systems start with a base version of the document and
+then save just the changes you made at each step of the way.
+
+A version control system is a tool that keeps track of changes for us and
+helps us version and merge our files. It allows you to decide which changes make
+up the next version, called a [`commit`], and keeps useful metadata about them.
+The complete history of commits for a particular project and their metadata make
+up a `repository`. Repositories can be kept in sync across different computers
+facilitating collaboration among different people.
+
+- Better kind of backup.
+- Version control is like an unlimited *undo*.
+- Review history.
+- Restore older file versions.
+- Ability to undo mistakes.
+- Maintain several versions of the code at a time.
+- Version control also allows many people to work in parallel.
+
+### Changes are saved sequentially
+
+You can think of it as a tape: if you rewind the tape and start at the base
+document, then you can play back each change and end up with your
+latest version.
+
+![Changes Are Saved Sequentially](../assets/img/sections/play-changes.png)
+
+### Different Versions Can be Saved
+
+Once you think of changes as separate from the document itself, you
+can then think about "playing back" different sets of changes onto the
+base document and getting different versions of the document. For
+example, two users can make independent sets of changes based on the
+same document.
+
+![Different Versions Can be Saved](../assets/img/sections/versions.png)
+
+### Multiple Versions Can be Merged
+
+Unless there are `conflicts`, you can even play two sets of changes onto the same
+base document.
+
+![Multiple Versions Can be Merged](../assets/img/sections/merge.png)
+
+## Version control systems
+
+There are many different version control systems:
+
+- Git  `<<< We will use this VC system`
+- Mercurial (`hg`)
+- CVS
+- Subversion (`svn`)
+- ...
+
+```{important}
+Git != GitHub
+
+- Git: version control system tool to manage source code history.
+- GitHub: hosting service for Git repositories.
+```
+
+## Learn More
+
+If you want to see a complete material to dive in Version Control using Git, please:
+
+- visit our [SWD2: Version Control with Git and Github Course Material](https://arctraining.github.io/swd2_git/).
+- book a place in one of our Git/Github courses: [Book Here](https://uolr3.leeds.ac.uk/temcatsearch(bD1lbiZjPTUwMA==)/courses.htm?sap-params=Z2Rfa2V5d29yZHM9VmVyc2lvbiUyMENvbnRyb2wmZ2Rfc3R5cGU9JmdkX3R1dG9yPUxhc3QlMjBuYW1lJmRhdGUxPWRkJTJmbW0lMmZ5eXl5JmRhdGUyPWRkJTJmbW0lMmZ5eXl5JmRhdGUxPTAwLjAwLjAwMDAmZGF0ZTI9MDAuMDAuMDAwMCZwcm92aWRlcmxpc3Q9NTAwMjI0MjkmYW5kb3I9T1Imc29ydD1CRUdEQSZnZF9jYWxsaWQ9SU5JVElBTCZzdHlsZT0%3d)

book/sections/ide.md

@@ -0,0 +1,55 @@
+# IDE
+
+Using an Integrated development environment (IDE) will certainly save you time,
+but the advantages of using an IDE go beyond that. Below are some IDE advantages
+
+1. Syntax highlighting
+2. Text autocompletion
+3. Refactoring options
+4. Easily Importing libraries
+5. Build, compile, or run
+
+## Visual Studio Code
+
+You may already have a preferred IDE that you use regularly, however we strongly
+suggest that you use VS Code for this course and afterwards replicate the setup
+as you choose. If you already have VS Code installed please make sure it is
+updated to the latest version.
+
+To install VS Code follow the instructions [here](https://code.visualstudio.com/).
+
+Below are some VSC advantages
+
+1. IntelliSense: Go beyond syntax highlighting and autocomplete
+2. Run & Debug: Debug code right from the editor
+3. Built-in Git: Review diffs, stage files, and make commits right from the editor.
+4. Extensible and customizable: Install extensions to add new languages, themes, debuggers, and to connect to additional services.
+
+### VSC Example: automatically using black
+
+> Configure VSC to use Black
+
+Open Settings: Code (or File) > Preferences > Settings
+
+- Search for `python formatting provider` and choose `black`
+- Search for `format on save` and check the box to enable
+
+> Select interpreter
+
+Open `Command Palette`: View > `Command Palette..` (or `Ctrl+Shift+P`)
+
+- Search for `Python: Select Interpreter`
+- Choose the correct environment
+
+Now the Black package is going to fix your codes layout every time you save a
+code file.
+
+### VSC Extensions
+
+#### Useful Extensions
+
+- Extension: GitLens — Git supercharged
+- Extension: autoDocstring - Python Docstring Generator
+- Extension: Code Spell Checker
+- Extension: markdownlint
+- Extension: Markdown All in One