Chapter 2 exercises

Author: dham

doc/source/0_preface.rst

@@ -37,8 +37,7 @@ year courses with the sole objective of teaching students to programme well.
 This book is the text for the second of these courses. Named "Principles of
 Programming", the course aims to take students with a knowledge of basic Python
 programming (functions, loops, plotting and so forth) and introduce them to
-higher level programming concepts. The course has also been taught to master's
-students in the Mathematical Institute at the University of Oxford.
+higher level programming concepts.
 
 The objective of this course is to graduate better programmers. Material on
 new programming constructs and concepts is accompanied by chapters on good
@@ -68,11 +67,11 @@ This book is for anyone with mathematical, scientific, or engineering interests
 who would like to learn to be a more capable programmer. The mathematical
 examples assume that you know how to differentiate functions of one variable,
 but very little beyond that. Where examples or exercises employ other
-mathematics, such as cellular automata in :numref:`style` and groups in
-:numref:`abstract_data_types`, enough of the mathematics will be introduced
-that the reader should be able to understand the programming concept being
-explained, without necessarily understanding all of the mathematical details of
-the example.
+mathematics, such as cellular automata in :numref:`Chapter %s <style>` and
+groups in :numref:`Chapter %s <abstract_data_types>`, enough of the mathematics
+will be introduced that the reader should be able to understand the programming
+concept being explained, without necessarily understanding all of the
+mathematical details of the example.
 
 This is not an introduction to basic Python: it's assumed that the reader knows
 the sort of basic Python usually covered in a first programming or
@@ -83,9 +82,9 @@ values, as well as dictionaries, lists, and tuples.
 
 Many introductory Python courses exclusively use Jupyter notebooks, so nothing
 beyond that is assumed. Getting set up with a working Python installation is
-covered in :numref:`introduction` while the Python command line and using a
-text editor to create programmes in files are introduced from scratch in
-:numref:`programs_files`.
+covered in :numref:`Chapter %s <introduction>` while the Python command line
+and using a text editor to create programmes in files are introduced from
+scratch in :numref:`Chapter %s <programs_files>`.
 
 How to use this book
 --------------------
@@ -123,18 +122,17 @@ The exercises
 .............
 
 At the end of each chapter are exercises. These usually depend on a skeleton
-code which is available on GitHub. Sometimes you might be asked to complete a piece of code while on other
-occasions you'll need to write a whole Python module from scratch. Each set of
-exercises will come with a matching set of tests. These are small programs which
-check whether your code produces the correct responses to a range of inputs.
-Tests like this provide immediate feedback and enable you to know how you are
-doing. Links to the skeleton code for each chapter are provided at:
+code which is available on GitHub. Sometimes you might be asked to complete a
+piece of code while on other occasions you'll need to write a whole Python
+module from scratch. Each set of exercises will come with a matching set of
+tests. These are small programs which check whether your code produces the
+correct responses to a range of inputs. Tests like this provide immediate
+feedback and enable you to know how you are doing. Links to the skeleton code
+for each chapter are provided at:
 
         `https://object-oriented-programming.github.io/edition1/exercises.html
         <https://object-oriented-programming.github.io/edition1/exercises.html>`__
 
-The mechanism for accessing the exercises will be covered in
-:numref:`introduction`.
 
 Conventions employed
 --------------------

doc/source/1_introduction.rst

@@ -76,7 +76,7 @@ are:
     1. Python version 3.6 or later.
     2. Git (the revision control system we're going to use).
     3. A Python-aware text editor or :term:`integrated development
-       environment`. Visual Studio Code is recommended, and all the
+       environment` (IDE). Visual Studio Code is recommended, and all the
        instructions will assume that this is what you are using.
 
 .. only:: book
@@ -104,6 +104,11 @@ are:
     Installation instructions for these pieces of code are provided `on this
     page <https://object-oriented-programming.github.io/installation.html>`__`.
 
+This is not a course about Git, but a minimal familiarity with Git and GitHub
+will be needed in order to work with the examples. :numref:`Appendix %s <git>`
+provides an elementary introduction to these tools for readers not already
+familiar with them.
+
 Python versions
 ...............
 
@@ -147,7 +152,7 @@ whole bunch of Python packages. It's highly desirable have a predictable
 programming environment in which the experiments you're doing don't interfere
 with anything else for which you might be using Python, and conversely which
 remains unaffected by any packages you may have installed elsewhere. This
-separation can be achieved by doing everything in a Python :term:`virtual
+separation can be achieved by working in a Python :term:`virtual
 environment`, or :term:`venv`. 
 
 A virtual environment is a folder containing a local installation of Python
@@ -164,7 +169,7 @@ call this anything you like. On my computer this is called
 :file:`principles_of_programming`. You can create this folder using the
 Windows File Explorer, Mac Finder, or by typing the following in a terminal:
 
-.. code-block::
+.. code-block:: console
 
     $ mkdir principles_of_programming
 

doc/source/2_programs_in_files.rst

@@ -5,7 +5,7 @@ Programs in files
 
 In this chapter we will start to learn how to combine pieces of code into
 larger units, and how to package up your code so that you or others can do the
-same. You will previously have written Python code in Jupyter notebooks, and
+same. You may previously have written Python code in Jupyter notebooks, and
 possibly used an interactive Python environment such as IPython. Jupyter
 notebooks are an excellent platform for writing and documenting short pieces of
 code. However, they are much less good for writing code which is designed to be
@@ -327,7 +327,7 @@ want: it clearly separates the names in the module from the names we
 have defined ourselves, and makes it very obvious to a reader where
 the names come from. The downside is that names in namespaces can be
 quite long and cumbersome, which is particularly inconvenient if names
-are to be used frequently or in the middle of formulae: you probably
+are to be used frequently or in the middle of expressions: you probably
 don't really want to write :func:`math.sin` in every trig formula you
 ever write. One alternative is to rename the module on import. This is
 achieved using the keyword :keyword:`as <import>` in an import statement. For example,
@@ -449,7 +449,7 @@ they make up the Python package.
     This is not really a part of the package at all, but the
     :file:`my_package` folder needs to be in some folder, and this is a
     reminder that all your work should be in a revision control system
-    such as :ref:`git <fons:git>`. It would be usual for
+    such as :ref:`Git <git>`. It is usual for
     package folders to be contained immediately in the top level of
     the repository, in the manner shown here.
 
@@ -927,7 +927,9 @@ Exercises
 
 Before attempting the exercises, ensure that you have obtained the software
 tools described in :numref:`tools` and set up a working folder and
-:term:`virtual environment` as described in :numref:`venv`.
+:term:`virtual environment` as described in :numref:`venv`. If you're not
+already familiar with Git and GitHub then you will also need to work through
+:numref:`Appendix %s <git>` to learn enough to do the exercises.
 
 .. .. panels::
 ..     :card: quiz shadow
@@ -943,40 +945,68 @@ tools described in :numref:`tools` and set up a working folder and
 ..     you will use for this course on your computer. Start with an overall folder
 ..     for the module, and create a virtual environment in that module.
 
+.. only:: book
+
+    .. raw:: latex
+
+        \clearpage
+
 .. _course_repo:
 
 .. proof:exercise::
 
-    Visit the `GitHub repository for these notes
-    <https://github.com/object-oriented-python/object-oriented-programming>`__.
-    Clone that git repository into your course folder, and install the Python
-    package it contains into your virtual environment. Check that it has
-    installed correctly by installing Pytest, and running:
+    .. only:: not book
+            
+        Visit the `GitHub repository for this book
+        <https://github.com/object-oriented-python/object-oriented-programming>`__.
+        Clone that git repository into your course folder, and install the Python
+        package it contains into your virtual environment. Check that it has
+        installed correctly by installing Pytest, and running:
+
+    .. only:: book
+            
+        Visit the GitHub repository for this book. [#book_repo]_
+        Clone that git repository into your working folder, and install the Python
+        package it contains into your virtual environment. Check that it has
+        installed correctly by installing Pytest, and running:
 
     .. code-block:: console
 
         (PoP_venv) $ pytest tests/test_fibonacci.py
 
-    You could also run iPython,  import :mod:`fibonacci` and try out
+    You could also run IPython,  import :mod:`fibonacci` and try out
     :func:`fibonacci.fib <fibonacci.fibonacci.fib>` yourself.
 
 .. proof:exercise::
 
-    Accept the `first GitHub Classroom assignment for this module
-    <https://classroom.github.com/a/VltGa-Xl>`__ and clone it into your course folder. The assignment
-    repository just contains a :file:`README` and some tests. Your job in the
-    following exercises will be to populate it with the remaining content.
+    .. only:: not book
+
+        Using the information on the `book website
+        <https://object-oriented-programming.github.io/edition1/exercises.html>`__
+        create your first exercise repository for this module and clone it
+        into your working folder. The exercise repository just contains a
+        :file:`README` and some tests. Your job in the following exercises will be
+        to populate it with the remaining content.
+
+    .. only:: book
+
+        Using the information on the `book website` [#exercise_page]_
+        create your first exercise repository for this module and clone it
+        into your working folder. The exercise repository just contains a
+        :file:`README` and some tests. Your job in the following exercises will be
+        to populate it with the remaining content.
+
 
 .. proof:exercise::
 
     Create a new Python :term:`package` named :mod:`math_utils` containing a
     :term:`module` called :mod:`primes`. In the :mod:`primes` module define a
     function :func:`isprime` which takes in a single integer argument and
-    returns `True` or `False` depending on whether or not the argument is prime.
-    There is no need to be sophisticated in the algorithm used to check for
-    primeness, simply checking whether the number is zero modulo any of the
-    integers less than its square root will be fine. Test your code by running
-    the following in your week 2 exercise repository:
+    returns `True` or `False` depending on whether or not the argument is
+    prime. There is no need use a sophisticated algorithm, simply checking
+    whether the number is zero modulo any of the integers less than its square
+    root will be fine. Test your code by running the following in the exercise
+    repository:
 
     .. code-block:: console
 
@@ -1029,4 +1059,10 @@ tools described in :numref:`tools` and set up a working folder and
     <https://docs.python.org/3/reference/simple_stmts.html#import>`__
 
 .. [#packaging] `https://packaging.python.org
-    <https://packaging.python.org/tutorials/packaging-projects/>`__ 
+    <https://packaging.python.org/tutorials/packaging-projects/>`__ 
+
+.. [#book_repo] `https://github.com/object-oriented-python/object-oriented-programming
+    <https://github.com/object-oriented-python/object-oriented-programming>`__
+
+.. [#exercise_page] `https://object-oriented-programming.github.io/edition1/exercises.html
+    <https://object-oriented-programming.github.io/edition1/exercises.html>`__