Lots of github

Author: dham

doc/source/1_introduction.rst

@@ -63,6 +63,8 @@ abstraction in mathematics, abstraction in coding is a form of
 constructive laziness: it simultaneously allows the mathematician to
 achieve more and do less work.
 
+.. _tools:
+
 Obtaining the right software tools
 ----------------------------------
 
@@ -127,6 +129,8 @@ Python you use.
     which were introduced in Python 3.6, so the code will not work in earlier
     versions of Python.
 
+.. _venv:
+
 Setting up a Python virtual environment
 ---------------------------------------
 
@@ -191,24 +195,26 @@ there then open the `View` menu and select `Terminal` to make it appear.
 
 The most straightforward way to create a venv is on the terminal
 command line, not from within Python itself. This is accomplished
-using Python's :mod:`venv` package. For example, to create a venv
-called `my_venv` on Windows, you would type:
+using Python's :mod:`venv` package. The venv has to be given a name. You will
+want this to be short, but distinctive enough that you know which venv you are
+using. For example, to create a venv
+called `PoP_venv` on Windows, you would type:
 
 .. code-block:: console
 
-    > py -m venv my_venv
+    > py -m venv PoP_venv
 
 while on Mac or Linux you would type:
 
 .. code-block:: console
 
-    $ python3 -m venv my_venv
+    $ python3 -m venv PoP_venv
 
 Don't forget that the `>` or `$` stands for the command prompt: you don't
-type it. This command will create the folder `my_venv` and various
+type it. This command will create the folder `PoP_venv` and various
 subfolders containing things like the Python program itself and space
 for any packages which you install in the venv. If there was already a
-file or folder called `my_venv` in the current folder then you'll get
+file or folder called `PoP_venv` in the current folder then you'll get
 an error, so make sure you choose a new name.
 
 .. note::
@@ -218,7 +224,7 @@ an error, so make sure you choose a new name.
     multiple Python installations on your computer then you might end up
     running the wrong one. If this happens then you will need to type the full
     path to the Python you want to use (starting with `/` on Mac or Linux or
-    `\` on Windows). Once the venv is installed and activated, it will be
+    `\\` on Windows). Once the venv is installed and activated, it will be
     sufficient to type `python` as the venv will ensure that this is the
     correct version.
 
@@ -229,7 +235,7 @@ again. In the bash or zsh shells you would type:
 
 .. code-block:: console
 
-   $ rm -rf my_venv
+   $ rm -rf PoP_venv
 
 .. warning::
 
@@ -248,27 +254,27 @@ Linux you would type:
 
 .. code-block:: console
 
-    $ source my_venv/bin/activate
+    $ source PoP_venv/bin/activate
 
 while using bash on Windows you would type:
 
 .. code-block:: console
 
-    $ source my_venv/Scripts/activate
+    $ source PoP_venv/Scripts/activate
 
 If using PowerShell on Windows then you type:
 
 .. code-block:: powershell
 
-    > .\my_venv\Scripts\activate.ps1
+    > .\PoP_venv\Scripts\activate.ps1
 
 Obviously, you would use the folder name of your venv instead of
-`my_venv`. In either case, your command prompt will change to indicate
+`PoP_venv`. In either case, your command prompt will change to indicate
 that you are now using the venv. It might look something like:
 
 .. code-block:: console
 
-   (my_venv) $
+   (PoP_venv) $
 
 Any subsequent invocations of Python commands such as `python3` will
 now use the version from the venv, with access to whatever packages
@@ -285,8 +291,16 @@ for the correct activation command.
 
         > Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
-    For further information, see :doc:`the official Python venv documentation
-    <library/venv>`.
+    .. only:: not book
+
+        For further information, see :doc:`the official Python venv documentation
+        <library/venv>`.
+
+    .. only:: book
+
+        For further information, see the official Python venv documentation.
+        [#venv]_
+
 
 .. hint::
 
@@ -305,13 +319,13 @@ Python package :doc:`Pip <pip:index>`, which you will usually find
 pre-installed in your Python installation. Pip has many usage options, which
 enable a large number of different installation configurations. However, for
 most users most of the time, a few simple pip commands suffice. As with
-:term:`venv` creation, package installation is best accomplished from the
+venv creation, package installation is best accomplished from the
 terminal and not from within Python itself. Don't forget to activate the venv!
 
 .. _install-from-pypi:
 
 Installing packages from PyPI
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.............................
 
 `PyPI <https://pypi.org>`__ is the Python Package Index. It is the
 official download location for publicly released Python packages which
@@ -324,7 +338,7 @@ terminal command:
 
 .. code-block:: console
 
-   (my_venv) $ python -m pip install numpy
+   (PoP_venv) $ python -m pip install numpy
 
 It is also possible to invoke pip directly using the command `pip3`,
 but there are some circumstances where that might result in pip using
@@ -338,7 +352,7 @@ Pip can also be used to upgrade a package to the latest version:
 
 .. code-block:: console
 
-   (my_venv) $ python -m pip install --upgrade numpy
+   (PoP_venv) $ python -m pip install --upgrade numpy
 
 Glossary
 --------
@@ -389,3 +403,10 @@ Glossary
 ..     :ref:`Live Share instructions <vscode-liveshare>`. 
 ..     Ensure that each of you can start a Live Share session and have the other
 ..     successfully join, and that all of you can edit files.
+
+.. only:: book
+
+    .. rubric:: Footnotes
+
+    .. [#venv] `https://docs.python.org/3/library/venv.html
+        <https://docs.python.org/3/library/venv.html>`__ 

doc/source/2_programs_in_files.rst

@@ -67,13 +67,13 @@ active, we can install it by running:
 
 .. code-block:: console
 
-    (my_venv) $ python -m pip install ipython
+    (PoP_venv) $ python -m pip install ipython
 
 IPython can now be run by simply typing:
 
 .. code-block:: console
 
-    (my_venv) $ ipython
+    (PoP_venv) $ ipython
 
 This will result in output simiar to the following:
 
@@ -159,8 +159,8 @@ systems, you would type the following:
 
 .. code-block:: console
 
-    (my_venv) $ cd src
-    (my_venv) $ python hello.py
+    (PoP_venv) $ cd src
+    (PoP_venv) $ python hello.py
 
 The first of these commands,
 `cd` (*change directory*) switches the current folder to :file:`src`. The
@@ -608,7 +608,7 @@ you would type:
 
 .. code-block:: console
 
-   (my_venv) $ python -m pip install -e folder/
+   (PoP_venv) $ python -m pip install -e folder/
 
 replacing `folder` with the name of the top-level folder of your
 repository: the folder containing :file:`setup.py`. The option flag `-e`
@@ -708,7 +708,7 @@ your current environment using:
 
 .. code-block:: console
 
-    (my_venv) $ python -m pip install pytest
+    (PoP_venv) $ python -m pip install pytest
 
 Pytest tests
 ~~~~~~~~~~~~
@@ -767,8 +767,8 @@ We can then invoke the tests from the shell:
 
 .. code-block:: console
 
-    (my_venv) $ cd fibonacci
-    (my_venv) $ pytest tests
+    (PoP_venv) $ cd fibonacci
+    (PoP_venv) $ pytest tests
     ========================== test session starts ===========================
     platform darwin -- Python 3.7.7, pytest-5.4.1, py-1.8.1, pluggy-0.13.1
     rootdir: /Users/dham/docs/object-oriented-programming, inifile: setup.cfg
@@ -784,7 +784,7 @@ instead see something like:
 
 .. code-block:: console
 
-    (my_venv) $ pytest tests
+    (PoP_venv) $ pytest tests
     ========================== test session starts ===========================
     platform darwin -- Python 3.7.7, pytest-5.4.1, py-1.8.1, pluggy-0.13.1
     rootdir: /Users/dham/docs/object-oriented-programming, inifile: setup.cfg
@@ -821,14 +821,14 @@ that file as the argument to Pytest. For example:
 
 .. code-block:: console
 
-    (my_venv) $ pytest tests/test_fibonacci.py
+    (PoP_venv) $ pytest tests/test_fibonacci.py
 
 It is even possible to select an individual test to run, using a double colon
 `::` followed by the test name:
 
 .. code-block:: console
 
-    (my_venv) $ pytest tests/test_fibonacci.py::test_fibonacci_values
+    (PoP_venv) $ pytest tests/test_fibonacci.py::test_fibonacci_values
 
 Often if one test fails then the same problem in your code will cause a whole
 series of tests to fail, resulting in a very long list of error messages which
@@ -837,7 +837,7 @@ tells Pytest to stop after the first test fail. For example:
 
 .. code-block:: console
 
-    (my_venv) $ pytest -x tests
+    (PoP_venv) $ pytest -x tests
 
 The tests are often arranged in increasing order of sophistication, so the
 earlier tests are likely to catch the most basic errors in your code. For this
@@ -925,19 +925,23 @@ Glossary
 Exercises
 ---------
 
-.. panels::
-    :card: quiz shadow
+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`.
 
-    .. link-button:: https://bb.imperial.ac.uk/webapps/assessment/take/launchAssessment.jsp?course_id=_25965_1&content_id=_2054443_1&mode=cpview
-        :text: This week's quiz
-        :classes: stretched-link 
+.. .. panels::
+..     :card: quiz shadow
 
-.. proof:exercise::
+..     .. link-button:: https://bb.imperial.ac.uk/webapps/assessment/take/launchAssessment.jsp?course_id=_25965_1&content_id=_2054443_1&mode=cpview
+..         :text: This week's quiz
+..         :classes: stretched-link 
+
+.. .. proof:exercise::
 
-    Follow the :ref:`instructions on the Faculty of Natural Sciences Python
-    installation page <fons:python_folders>` to create the folder structure
-    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.
+..     Follow the :ref:`instructions on the Faculty of Natural Sciences Python
+..     installation page <fons:python_folders>` to create the folder structure
+..     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.
 
 .. _course_repo:
 
@@ -951,7 +955,7 @@ Exercises
 
     .. code-block:: console
 
-        (my_venv) $ pytest tests/test_fibonacci.py
+        (PoP_venv) $ pytest tests/test_fibonacci.py
 
     You could also run iPython,  import :mod:`fibonacci` and try out
     :func:`fibonacci.fib <fibonacci.fibonacci.fib>` yourself.
@@ -976,7 +980,7 @@ Exercises
 
     .. code-block:: console
 
-        (my_venv) $ pytest tests/test_exercise_2_4.py
+        (PoP_venv) $ pytest tests/test_exercise_2_4.py
 
     Then push your code to GitHub and check that the tests pass there too.