_episodes/03-packaging-installing.md: moving Pip section.

_episodes/03-packaging-installing.md

@@ -6,13 +6,13 @@ questions:
 - "How do I use my own functions?"
 - "How can I make my functions most usable for my collaborators?"
 objectives:
-- "Identify the components of a python package"
+- "Identify the components of a Python package"
 - "Apply a template for packaging existing code"
 - "Update the packaged project after modifying the code"
 - "Install and update a local or GitHub-hosted package"
 keypoints:
 - "Packaged code is reusable within and across systems"
-- "A python package consists of modules"
+- "A Python package consists of modules"
 - "Projects can be distributed in many ways and installed with a package manager"
 ---
 
@@ -52,7 +52,7 @@ Keep motivation as easing in  and gradually scaling up to stay inclusive -->
 
 ## Pip
 
-Pip is the most common package manager for python. Pip allows you to easily install python packages locally from your computer or from an online repository like the [Python Package Index (PyPI)](https://pypi.org/). Once a package is installed with pip, you can `import` that package and use it in your own code.
+Pip is the most common package manager for Python. Pip allows you to easily install Python packages locally from your computer or from an online repository like the [Python Package Index (PyPI)](https://pypi.org/). Once a package is installed with pip, you can `import` that package and use it in your own code.
 
 Pip is a command line tool. We'll start by exploring its help manual:
 
@@ -133,7 +133,7 @@ This shows the basic commands available with pip and and the general options.
 
 ## Python Modules
 
-A module is a piece of code that serves a specific purpose. In python, a module is written in a `.py` file. The name of the file is name of the module. A module can contain classes, functions, or a combination of both. Modules can also define variables for use, for example, [numpy](https://numpy.org/) defines the value of pi with `numpy.pi`.
+A module is a piece of code that serves a specific purpose. In Python, a module is written in a `.py` file. The name of the file is name of the module. A module can contain classes, functions, or a combination of both. Modules can also define variables for use, for example, [numpy](https://numpy.org/) defines the value of pi with `numpy.pi`.
 
 
 If a `.py` file is on the path, we can import functions from it to our current file. Open up Python, import `sys` and print the path.
@@ -193,7 +193,7 @@ and `numpy.random.rand`. respectively
 
 In this way, namespaces allow multiple packages to have functions of the same name without creating conflicts. Packages are namespaces or containers which can contain multiple modules.
 
-Making python code into a package requires no extra tools. We need to
+Making Python code into a package requires no extra tools. We need to
 
 - Create a directory, named after our package.
 - Put modules (`.py` files) in the directory.
@@ -208,7 +208,7 @@ Our final package will look like this:
 │   └── module-b.py  
 └── setup.py
 
-The `__init__.py` file tells python that the directory is supposed to be tread as a package.
+The `__init__.py` file tells Python that the directory is supposed to be tread as a package.
 
 Let's create a package called **conversions** with two modules **temperature** and **speed**.
 
@@ -302,7 +302,7 @@ The init file is the map that tells Python what our package looks like.  It is
 also what tells Python a directory is a module. An empty init file marks a
 directory as a module. By adding import code, we can make our package easier to use.
 
-Now, if we launch a new python terminal from this directory, we can import the package **conversions**
+Now, if we launch a new Python terminal from this directory, we can import the package **conversions**
 
 e.g
 
@@ -370,24 +370,108 @@ from a local directory.
 > {: .output}
 {: .callout}
 
-So, to install our package, we can run:
+So, to install our package, we can use **Pip**. [Pip](https://pypi.org/project/pip/) is a package manager,
+that is, a package that install packages. We are going to learn more about it in the next section.
+For now, we can run:
 
 ~~~
 cd conversions
 pip install -e .
 ~~~
 {: .language-bash}
-The `-e` flag (aka `--editable`) tells pip to install this package in editable mode. This allows us to make 
+The `-e` flag (aka `--editable`) tells Pip to install this package in editable mode. This allows us to make 
 changes to the package without re-installing it. Analysis code can change dramatically over time, so this is a 
 useful option!
 
+## Pip
+
+Pip is the most common package manager for python. Pip allows you to easily install python packages locally from your computer or from an online repository like the [Python Package Index (PyPI)](https://pypi.org/). Once a package is installed with pip, you can `import` that package and use it in your own code.
+
+Pip is a command line tool. We'll start by exploring its help manual:
+
+~~~
+pip
+~~~
+{:.language-bash}
+
+The output will look like this
+~~~
+Usage:   
+  pip <command> [options]
+
+Commands:
+  install                     Install packages.
+  download                    Download packages.
+  uninstall                   Uninstall packages.
+  freeze                      Output installed packages in requirements format.
+  list                        List installed packages.
+  show                        Show information about installed packages.
+  check                       Verify installed packages have compatible dependencies.
+  config                      Manage local and global configuration.
+  search                      Search PyPI for packages.
+  wheel                       Build wheels from your requirements.
+  hash                        Compute hashes of package archives.
+  completion                  A helper command used for command completion.
+  help                        Show help for commands.
+
+General Options:
+  -h, --help                  Show help.
+  --isolated                  Run pip in an isolated mode, ignoring
+                              environment variables and user configuration.
+  -v, --verbose               Give more output. Option is additive, and can be
+                              used up to 3 times.
+  -V, --version               Show version and exit.
+  -q, --quiet                 Give less output. Option is additive, and can be
+                              used up to 3 times (corresponding to WARNING,
+                              ERROR, and CRITICAL logging levels).
+  --log <path>                Path to a verbose appending log.
+  --proxy <proxy>             Specify a proxy in the form
+                              [user:passwd@]proxy.server:port.
+  --retries <retries>         Maximum number of retries each connection should
+                              attempt (default 5 times).
+  --timeout <sec>             Set the socket timeout (default 15 seconds).
+  --exists-action <action>    Default action when a path already exists:
+                              (s)witch, (i)gnore, (w)ipe, (b)ackup, (a)bort).
+  --trusted-host <hostname>   Mark this host as trusted, even though it does
+                              not have valid or any HTTPS.
+  --cert <path>               Path to alternate CA bundle.
+  --client-cert <path>        Path to SSL client certificate, a single file
+                              containing the private key and the certificate
+                              in PEM format.
+  --cache-dir <dir>           Store the cache data in <dir>.
+  --no-cache-dir              Disable the cache.
+  --disable-pip-version-check
+                              Don't periodically check PyPI to determine
+                              whether a new version of pip is available for
+                              download. Implied with --no-index.
+  --no-color                  Suppress colored output
+~~~
+{: .output}
+
+This shows the basic commands available with pip and and the general options.
+
+> ## Exercise
+> 1. Use pip to install the `sphinx` package, we will need it later.
+> 2. Choose a pip command and look up its options. Discuss the command with your
+> neighbour.
+>
+> > ## Solution
+> >
+> > ~~~
+> > pip install sphinx
+> > ~~~
+> > {: .language-bash}
+> {: .solution}
+{: .challenge}
+
+
 Now we can try importing and using our package.
 
 ## Command Line Tools
 
 FIXME: how to make a tool command line installable
 
-More details on this may be found at [on the python packaging documentation site](https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html)
+More details on this may be found at [on the Python packaging documentation site](https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html)
 
 ## Getting a Package from A Colleague