Release candidate.

Author: dham

doc/source/1_introduction.rst

@@ -101,8 +101,8 @@ are:
 
 .. only:: html
 
-    Installation instructions for these pieces of code are provided `on this
-    page <https://object-oriented-programming.github.io/installation.html>`__.
+    Installation instructions for these pieces of code are provided :doc:`on
+    this page <installation>`.
 
 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>`

doc/source/_static/video_cover_page.svg

@@ -29,7 +29,10 @@
       <ul>
           <li class="page_item"><a href="{{ pathto('index.html', 1) }}" title="Book">Book</a></li>
           <li class="page_item"><a href="{{ pathto('videos.html', 1) }}" title="Videos">Videos</a></li>
-          <li class="page_item"><a href="{{ pathto('exercises.html', 1) }}" title="Exercises">Exercises</a></li>
+          <li class="page_item"><a href="{{ pathto('exercises.html', 1) }}"
+          title="Exercises">Exercises</a></li>
+          <li class="page_item"><a href="{{ pathto('installation.html', 1) }}" title="Installation">Installation</a></li>
+
       </ul>
     </div><!-- .menu -->
   </div><!-- #access -->

doc/source/_themes/finite_element/layout.html

@@ -58,7 +58,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Object oriented programming'
+project = u'Object-oriented Programming'
 author = u'David A. Ham'
 copyright = u'2019-2021, David A. Ham'
 
@@ -246,7 +246,7 @@
 %\hypersetup{urlcolor=externallinkcolor}
 \hypersetup{urlcolor=black}
 \usepackage{poptitle}
-\subtitle{in Python for mathematicians}
+\subtitle{in Python for Mathematicians}
 \edition{2021}
 \makeatletter
    \fancypagestyle{normal}{
@@ -268,7 +268,7 @@
     # Imperial lecture notes version.
     preamble = r"""
 \usepackage{imperialmathnotes}
-\subtitle{in Python for mathematicians}
+\subtitle{in Python for Mathematicians}
 \imperialmathnotesvolume{2}
 \edition{2021}
 """

doc/source/conf.py

@@ -1,3 +1,5 @@
+.. _exercises:
+
 Exercise code
 =============
 

doc/source/exercises.rst

@@ -20,15 +20,19 @@
 
 .. only:: html
 
-   This is the online textbook for MATH50009 Principles of Programming, a
-   second year object oriented programming module offered to mathematics
-   undergraduates at Imperial College London. Read the introductory chapter for
-   information on how to go about doing the module week by week.
-
-   If you're not taking the module at Imperial, you should nonetheless feel
-   free to use this material to learn object-oriented programming in Python. I
-   would be very interested to hear from anyone interested in using it to
-   teach.
+   Welcome to the website for the book Object-oriented Programming in Python
+   for Mathematicians. Here you'll find the full hyperlinked book text, as well
+   as consolidated lists of the accompanying :doc:`videos <videos>` and
+   :doc:`exercise repositories <exercises>`.
+
+   .. image:: images/cover.png
+      :width: 10em
+      :align: right
+      :target: https://fixme.foo
+
+   The complete book text is available on this website. However, if you'd
+   like to have a physical copy, then please `buy the book
+   <https://fixme.foo>`__.
 
 .. container:: preface
 

doc/source/images/cover.png

@@ -1,39 +1,144 @@
+Installing the necessary software
+=================================
+
+In order to do the exercises in this book, you will need Python, Git, and a
+suitable text editor or :term:`Integrated Development Environment`. Visual
+Studio Code is recommended as the :term:`IDE`.
+
+Instructions are provided here for Windows, MacOS, and Linux. Chromebook users
+can follow the Linux instructions if they first `activate Linux on their
+Chromebook <https://support.google.com/chromebook/answer/9145439>`__.
+
+Homebrew for Mac
+----------------
+
+The easiest way to install additional programming software on a Mac is to first
+install the Homebrew package manager. Open a terminal (press :kbd:`⌘` +
+:kbd:`space` to open Spotlight Search and then type `terminal` in the search
+window) and run the following command:
+
+.. code-block:: console
+
+    $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+
+Don't type the :kbd:`$`. That's the terminal prompt (it might appear as another
+symbol such as :kbd:`%` for you).
+
+This will start the install process, and ask you for confirmation before
+installing Homebrew. 
+
+Further documentation about Homebrew and its dependencies is available on the
+`Homebrew website <https://brew.sh>`_.
+
 
 Python 
-......
+------
 
 There are a number of different ways of obtaining Python, depending a little on
-which operating system your computer runs. The options suggested here are 
+which operating system your computer runs. The routes suggested here are ones
+that have been easiest for students taking the course at Imperial, however any
+sufficiently recent Python should be sufficient.
+
+Windows
+.......
+
+Install `Python from the Microsoft Store
+<https://www.microsoft.com/en-us/p/python-310/9pjpw5ldxlz5>`__. 
+
+MacOS
+.....
+
+MacOS comes with Python 3, but it's a cut down version not suitable for our
+purposes. Instead, install Python from Homebrew:
+
+.. code-block:: console
+
+    $ brew install python
+
+Linux
+.....
+
+Every Linux distribution ships with Python 3 by default. However, they don't
+always have the Python package manager Pip installed by default. We will need
+that so you'll need to use your distribution's package manager to install it.
+For example on Ubuntu or Debian you would run:
+
+.. code-block:: console
+
+    $ sudo apt install python3-pip
+
+while on Fedora and related distributions you would run:
+
+.. code-block:: console
 
-Follow the :doc:`FoNS Python instructions <fons:python>`. We will exclusively
-use :ref:`virtual environments <fons:python_virtual_environments>` so it doesn't matter at
-all whether you use Python from Anaconda or from another source. Mac users
-should note, though that the built-in Python will not do, so you should use
-either Homebrew or Anaconda.
+    $ sudo dnf install python-pip
 
 Git
-...
+---
 
 Git is a revision control system. Revision control systems enable you to keep
 track of the different versions of a piece of code as you work on them, and to
 have these versions on different computers as well as backed up in the cloud. We
 will use Git and GitHub classroom as a mechanism for distributing, working with
 and submitting code exercises.
 
-.. warning::
+Windows
+.......
+
+Download and install the `Git package <https://git-scm.com/download/win>`__.
+
+MacOS
+.....
+
+MacOS comes with a perfectly acceptable Git installation. However you can also
+install a more recent version from Homebrew:
+
+.. code-block:: console
+
+    $ brew install git
+
+Linux
+.....
+
+Use your distribution package manager to install Git. For example on Ubuntu or
+Debian:
+
+.. code-block:: 
+
+    $ sudo apt install git-all
+
+On Fedora:
+
+.. code-block::
+
+    $ sudo apt install git-all
 
-    When you come to the assessable programming tests that make up 100% of the
-    assessment for this module, the code will be distributed and submitted using
-    Git. It is therefore essential that you incorporate Git into your day to day
-    workflow so that when you come to the test, it's second nature. You will not
-    receive marks for test answers that are not committed and pushed.
 
 Visual Studio Code
-..................
+------------------
 
 Visual Studio Code is a Python-aware Integrated Development Environment (IDE).
 This means that it incorporates editing files with other programming features
-such as :ref:`debugging`, Git support, and built-in :ref:`terminal
-<terminal-vscode>`. Visual Studio Code also provides an incredibly useful remote
-collaborative coding feature called Live Share. This will be very useful for
-getting remote help from an instructor. 
+such as :ref:`debugging`, Git support, and built-in terminal. 
+
+Windows
+.......
+
+`Download and install the package <https://code.visualstudio.com/download>`__.
+
+MacOS
+.....
+
+Use Homebrew to install Visual Studio Code:
+
+.. code-block:: console
+
+    $ brew install visual-studio-code
+
+
+Linux
+.....
+
+`Download the package <https://code.visualstudio.com/download>`__ and then use
+your package manager to install it `following these instructions
+<https://code.visualstudio.com/docs/setup/linux>`__.

doc/source/index.rst

@@ -1,3 +1,5 @@
+.. _videos:
+
 Videos
 ======