StructureChange-chapter1

.gitignore

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

book/Python_Toolbox.md

@@ -1,41 +1,7 @@
-(toolbox)=
 # Python Toolbox
 
-This page describes several ways to write and execute Python code, some of which don't require any installation on your computer and work entirely in a web browser! These approaches are described in the sections below, and are based on the tools IPython and Jupyter Notebooks.
+% This page is a placeholder to ensure that links from previous years don't break.
+% This works as long as `only_build_toc_files: false` (default)
 
-**IPython** is an interactive Python interpreter that adds features that are useful for engineering, such as command history or inline display of figures. As you will see below, you can enter multiple lines of text and evaluate them at once; this is often referred to as a *cell* of code. In a nutshell, if you string many of these cells together into a single digital document, you more or less end up with a **Jupyter Notebook**; this leverages the power of IPython by allowing you to type, run and save the cells in any order, as well as type formatted text in between. Together, these two tools make up our toolbox for this course, and, as you will see, both of them can run in your internet browser, so there is no need to install special software!
-
-## Interactive Pages
-
-This course is powered by a special software (the [Sphinx-Thebe](https://github.com/executablebooks/sphinx-thebe) that allows you to run Python code in your browser and gives you an experience that is more or less identical the the "standard" Jupyter Notebook experience you would have on your own computer if you installed the dedicated software. You can access this tool by clicking on the rocket icon ({fa}`rocket`) at the top right of a page where this is enabled. 
-
-(calculator)=
-## IPython: Your Primary Python Calculator
-
-Below is an example of an IPython interpreter embedded in this webpage, which we refer to as our **Python Calculator**. Note that the square brackets with numbers (e.g, `[1]: ...`) are a feature of IPython that keeps track of the cells you have run: the first (pre-loaded) command is a print statement that executes once the interpreter is ready for use. You can try entering code yourself (for example, type `x=2`) and executing it using `Shift+Enter`. You just defined a variable! Note that typing `Enter` in the interpreter adds extra lines, it does not execute the cell. Try entering multiple lines, for example, `3*x`, `Enter` and `print(x)`, then execute. Can you tell what happened?
-
-<iframe
-    src="https://tudelft-citg.github.io/learn-python-calculator/repl/index.html?toolbar=1&kernel=python&code=print(%27You%20may%20begin!%27)"
-    width="750"
-    height="400"
-    style="border:2px solid powderblue"
-></iframe>
-
-The simple exercise above should be all you need to get started with this course. Throughout this course we encourage you to the Python Calculator in a new browser tab, which will allow you to read the exercise and run code side by side. You can test it <a href="https://tudelft-citg.github.io/learn-python-calculator/repl/index.html?toolbar=1&kernel=python&code=print(%27You%20may%20begin!%27)" target="_blank">here</a> in a new tab. When the console is critical for completing the exercises in a certain chapter, a drop-down note will be added that includes a special link inside, just like this:
-
-`````{admonition} Open the Python Calculator for this page
-:class: tip, dropdown
-Click this <a href="https://tudelft-citg.github.io/learn-python-calculator/repl/index.html?toolbar=1&kernel=python&code=print('You may begin!')" target="_blank">link</a> and wait until the message "<tt>You may begin!</tt>" is printed to start evaluating code. More information about this tool can be found [here](calculator). 
-
-Remember that most pages in this course can also be run interactively using the {fa}rocket icon above (read more about it [here](toolbox)).
-`````
-
-All exercises in this course can be completed using only the Python Calculator. We hope you find it to be a simple but useful way to practice and learn the Python programming language.
-
-```{note}
-A special instance of the Python Calculator is set up for each page which pre-loads a few packages needed to complete the exercise. Make sure you use link that is on the page of the exercises you are working on. 
-```
-
-## Anaconda: Python on Your Computer
-
-If you want to explore Python programming and Jupyter ecosystems beyond the exercises covered in this course, it might be worthwhile to install a Python distribution on your own computer. The most common and easiest way to do this is with [Anaconda](https://www.anaconda.com/download). Installation instructions are not included in this course, but you can find plenty of website of videos that cover this, as well as using the Anaconda Navigator to open a Jupyter Lab or Jupyter Notebook environment. Most of the pages in this online textbook can be downloaded in the form of a Jupyter Notebook file (a file ending with `.ipynb`): open it via one of the Jupyter environments and you are ready to go!
+```{include} ./toolbox.md
+```

book/Python_intro.md

@@ -1,60 +1,7 @@
-# Introduction to Programming and Python
+# Programming and Python
 
-## Why do you need Python? 
-
-Python is a computer programming language that is widely used in both academia and industries related to Civil Engineering, Environmental Engineering and Applied Earth Sciences. Being skilled in Python will help you on multiple occasions, including in your master courses. 
-
-## What can computers do for us?
-As an engineer or scientist, you will deal with units of information which are called <b>data</b>. The most important tasks that a computer can do for us are:
-
-1. Reading data
-2. Processing data
-3. Visualizing data
-
-These are tasks that require many repetitions and high precision.
-
-_1. Reading data_
-Reading data means the computer acquires data from a source and places it into its volatile memory for processing. Volatile memory keeps the data stored until the power supply is interrupted. The way data is stored in a computer determines how the computer will be able to use it.
-
-_2. Processing data_
-Data processing is the manipulation of the stored data in a system. After processing data by performing transformations, calculations, and more, you get an output; results.
-
-_3. Visualizing data_
-We map data (original or found) to graphic elements to communicate clearly and efficiently the information contained in the data. A graphic element is an element of a chart, such as a line or a point in the chart.
-
-## What is programming?
-
-Programming is giving your computer a list of instructions for computations in a language it can understand. In your case, this language is Python. A computation is a series of arithmetical ("math") and non-arithmetical ("non-math") steps that transform input to output (result).
-There are five different kinds of instructions for computations you use. By ordering and combining them, the computer can achieve results that fulfill the three tasks described earlier. The five kinds of instructions are:
-
-<b>input:</b>
-    Insert data from a file, the network, other devices, or simply by typing it in.
-
-<b>output:</b>
-    Display data on the screen, save them in a file, send it over the network, etc.
-
-<b>math:</b>
-    Perform basic mathematical operations like addition and multiplication.
-
-<b>conditional execution:</b>
-    Check for certain conditions before further instruction.
-
-<b>repetition:</b>
-    Perform instructions repeatedly, usually with some variation.
-
-
-## Introduction to Python
-
-The features of Python are what make it so popular. From the definition available on the corresponding Wiki page: <i> "Python is an <b>interpreted</b> <b>high-level</b> <b>general-purpose</b> <b>programming language</b>. Its design philosophy emphasizes code readability with its use of significant indentation. Its language constructs, as well as its object-oriented approach aim to help programmers write clear, logical code for small and large-scale projects."</i>. Quite a simple, yet concise description due to the meaning hidden behind each buzzword:
-
-<ul>
-<li> <b>Interpreted</b> means that there is an <b>interpreter</b>, a software tool, which reads and performs instructions written in Python. If your laptop, phone, or refrigerator has the interpreter, it can run most of the Python scripts!
-<li> <b>High-level</b> means that the programming language operates with abstract and more easily understandable concepts. In other words, you don't have to write or understand, code related to the hardware part of your machine (like binary code or assembly).
-<li> <b>General-purpose</b> means that the amount of Python application fields are endless. You can write Python scripts to manage and automate some primitive tasks for yourself, you can use it for data science, create your own machine / deep learning project, write your personal web application or even develop a game. 
-<li> <b> Programming language </b>means a set of specific predefined semantics, instructions, and syntax rules, which are used for writing necessary instructions. It is strictly defined, meaning that 99.99% of all errors in the code are made by the coder, not by the computer.
-</ul>
-
-Python scripts run with the help of a Python interpreter, but they can be written by using different software tools. Just like as you write your essay (you can type it in Word, Google Docs, Overleaf, or even on plain paper) you can write your Python code with different editors. You could use the default notepad, notepad++, find a proper website with an inbuilt code editor & interpreter (<a href="https://ideone.com/">IDEone</a>, for example), or use specialized Python code editors (Spyder, PyCharm, Visual Studio, etc). In all cases you will produce a set of instructions, which are stored in a file with the <b>*.py</b> extension and the interpreter will run it completely (from top to bottom).
-
-For this course we will use a slightly different approach to developing a Python script: <b>IPython</b> and <b>Jupyter Notebooks</b>. Think of these as two freely-available tools that add extra functionality to the basic Python programming language. As an example, imagine the camera built into your phone: on it's own it can take pictures, but there are many apps that add filters or sharing via social media that make the impact of your photos much more powerful. This is exactly what IPython and Jupyter Notebooks do for Python, and why they are such important tools in the toolbox of modern engineers. The next Chapter will introduce you to your Python Toolbox for this course!
+% This page is a placeholder to ensure that links from previous years don't break.
+% This works as long as `only_build_toc_files: false` (default)
 
+```{include} ./python.md
+```

book/_config.yml

@@ -35,6 +35,7 @@ html:
   use_issues_button: true
   use_repository_button: true
   use_edit_page_button: true
+  use_multitoc_numbering: false
   # announcement: "⚠️ This is not the final version of the book! The new version will be ready by July 1.⚠️"
   extra_navbar: |
       <div>

book/_toc.yml

@@ -5,17 +5,25 @@ format: jb-book
 root: introduction.md
 parts:
   - caption: Introduction
+    numbered: false
     chapters:
     - file: intro.md
       title: Course Overview
-    - file: Python_intro.md
+    - file: python.md
       title: Programming and Python
-    - file: Python_Toolbox.md
+    - file: toolbox.md
   - caption: Course Contents
+    numbered: true
     chapters:
-    - file: 01/Theory/01.ipynb
+    - file: basics.md
+      title: Basics
       sections:
-      - file: 01/Exercises/01.ipynb
+      - file: basics/hello.ipynb
+        title: Your First Script
+      - file: basics/variables.ipynb
+      - file: basics/operators.ipynb
+      - file: basics/functions.ipynb
+      - file: basics/Exercises/01.ipynb
     - file: 02/Theory/01.ipynb
       sections:
       - file: 02/Exercises/01.ipynb
@@ -46,11 +54,16 @@ parts:
       - file: 09/handling_errors.ipynb
       - file: 09/asserts.ipynb
   - caption: End of course survey
+    numbered: false
     chapters:
     - file: End-of-course-survey.md
   - caption: In a Nutshell
+    numbered: true
     chapters:
-    - file: 01/In_a_Nutshell/01.ipynb
+    - file: basics/nutshell.md
+      title: Basics
+      sections:
+      - file: basics/nutshell/01.ipynb
     - file: 02/In_a_Nutshell/01.ipynb
     - file: 03/In_a_Nutshell/01.ipynb
     - file: 04/In_a_Nutshell/01.ipynb

book/basics.md

@@ -0,0 +1,6 @@
+# Basics
+
+This chapter is all about getting some of the basics under your belt!
+
+% a short overview for this chapter
+

book/01/Exercises/01.ipynb → book/basics/Exercises/01.ipynb

@@ -47,23 +47,6 @@
     "#questions = [[q] for q in questions]"
    ]
   },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {
-    "id": "Pq9kETciS3VO",
-    "nbgrader": {
-     "grade": false,
-     "locked": true,
-     "solution": false
-    }
-   },
-   "source": [
-    "## Exercise 1.2.2\n",
-    "\n",
-    "<iframe src=\"https://tudelft.h5p.com/content/1292443730616813187/embed\" aria-label=\"Exercise 1.2.2\" width=\"1088\" height=\"637\" frameborder=\"0\" allowfullscreen=\"allowfullscreen\" allow=\"autoplay *; geolocation *; microphone *; camera *; midi *; encrypted-media *\"></iframe><script src=\"https://tudelft.h5p.com/js/h5p-resizer.js\" charset=\"UTF-8\"></script>\n"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -79,23 +62,6 @@
     "# display_quiz(questions[0])"
    ]
   },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {
-    "id": "cc546f8c",
-    "nbgrader": {
-     "grade": false,
-     "locked": true,
-     "solution": false
-    }
-   },
-   "source": [
-    "## Exercise 1.2.3\n",
-    "\n",
-    "<iframe src=\"https://tudelft.h5p.com/content/1292447891826229837/embed\" aria-label=\"Exercise 1.2.3\" width=\"1088\" height=\"637\" frameborder=\"0\" allowfullscreen=\"allowfullscreen\" allow=\"autoplay *; geolocation *; microphone *; camera *; midi *; encrypted-media *\"></iframe><script src=\"https://tudelft.h5p.com/js/h5p-resizer.js\" charset=\"UTF-8\"></script>"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -122,7 +88,9 @@
     }
    },
    "source": [
-    "## (Fixing) Exercise 1.2.4\n",
+    "<!-- exercise 1.2.4 -->\n",
+    "\n",
+    "## (Fixing) Exercise\n",
     "In the following exercise you will be using a piece of code, which was written by other people. It can contain concepts you haven't encountered yet but you need to practice with using code you don't understand completely. This is because you want to be able to use programs written by other people. Just like with calculators — if you add two numbers you get the result you expect to get. But you don't know exactly how that piece of plastics with electronic components performs that calculation.\n",
     "\n",
     "In order to approach the problem, start from the point of error. If your error cannot be solved there, work your way backwards through the code. Only try to understand the parts that are necessary to fix your problem, and avoid changing parts you know that work.\n",
@@ -200,7 +168,8 @@
     }
    },
    "source": [
-    "## (Searching) Exercise 1.2.5\n",
+    "<!-- exercise 1.2.5 -->\n",
+    "## (Searching) Exercise\n",
     "There are also other data types in Python, which were not mentioned in this part (in case they are not as useful or will be introduced later). For instance, <b>Complex</b> is one of them. The sad truth is that every software developer Googles a lot. It's not because she/he is lazy or incompetent. It is because programming languages are constantly updated and some tools are limited to a narrow field of applications. It is impractical to learn everything at once, therefore every coder has learned how to look up the functionality their task requires. Therefore, it is crucial for you to learn how to Google as well. Complex type is used in Python to represent complex numbers. If you haven't heard about them — a complex number is a number, which has a real and an imaginary part. For example, $x = 17 + 5i$. Here, $x$ is a complex number with a real part of $17$ and an imaginary part of $5$.\n",
     "\n",
     "Your task is to create a variable <code>my_complex_number</code> of Complex type and assign a $3 + 2i$ value to it. For that you will have to Google a bit. Try to look for something like \"Python complex variables\". Python is very popular and you will be able to find everything you need. Make sure to filter the information you need — not everything you will find will be useful for this simple exercise.\n"
@@ -241,7 +210,8 @@
     }
    },
    "source": [
-    "## Exercise 1.3.1\n",
+    "<!-- exercise 1.3.1 -->\n",
+    "## Exercise\n",
     "\n",
     "Given that we have a rectangle with a height of $3$ cm, width of $5$ cm and a cutout circle of radius $0.6$ cm, as shown below. \n",
     "\n",
@@ -307,29 +277,6 @@
     "#display_quiz(questions[4]+questions[5])"
    ]
   },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {
-    "id": "rax0w6q5S3WF",
-    "nbgrader": {
-     "grade": false,
-     "locked": true,
-     "solution": false
-    }
-   },
-   "source": [
-    "## Exercise 1.3.2\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "0b0d21d9",
-   "metadata": {},
-   "source": [
-    "<iframe src=\"https://tudelft.h5p.com/content/1292447925758635937/embed\" aria-label=\"Exercise 1.3.2\" width=\"1088\" height=\"637\" frameborder=\"0\" allowfullscreen=\"allowfullscreen\" allow=\"autoplay *; geolocation *; microphone *; camera *; midi *; encrypted-media *\"></iframe><script src=\"https://tudelft.h5p.com/js/h5p-resizer.js\" charset=\"UTF-8\"></script>"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,