Tweak readme and add advanced/readme

README.md

@@ -2,6 +2,62 @@
 
 
 This repository contains Jupyter notebooks and data for the 2018 WIN PyTreat.
+It contains two sets of practicals:
+
+- The `getting_started` directory contains a series of practicals intended
+  for those of you who are new to the Python programming language, or need
+  a refresher.
+
+- The `advanced_topics` directory contains a series of practicals on various
+  aspects of the Python programming language - these are intended for those
+  of you who are familiar with the basics of Python, and want to learn more
+  about the language.
+
+
+These practicals have been written under the assumption that FSL 5.0.10 is
+installed.
+
+
+## For attendees
+
+
+To run these notebooks in the `fslpython` environment, you must first install
+jupyter:
+
+
+```
+# If your FSL installation requires administrative privileges to modify, then
+# you MUST run these commands as root - don't just prefix each individual
+# command with sudo, or you will probably install jupyter into the wrong
+# location!
+#
+# One further complication - once you have become root, $FSLDIR may not be set,
+# so either set it as we have ione below, or make sure that it is set, before
+# proceeding.
+sudo su
+export FSLDIR=/usr/local/fsl
+source $FSLDIR/fslpython/bin/activate fslpython
+conda install jupyter
+source deactivate
+ln -s $FSLDIR/fslpython/envs/fslpython/bin/jupyter $FSLDIR/bin/fsljupyter
+```
+
+
+Then, clone this repository on your local machine, and run
+`fsljupyter notebook`:
+
+
+```
+git clone git@git.fmrib.ox.ac.uk:fsl/pytreat-2018-practicals.git
+cd pytreat-2018-practicals
+fsljupyter notebook
+```
+
+
+Have fun!
+
+
+## For contributors
 
 
 The upstream repository can be found at:
@@ -39,44 +95,27 @@ To contribute to the practicals:
    repository.
 
 
-To run these notebooks in the `fslpython` environment, you must first install
-jupyter:
-
+When you install `jupyter` above, you may also wish to install
+[`notedown`](https://github.com/aaren/notedown):
 
 ```
-# If your FSL installation requires administrative privileges to modify, then
-# you MUST run these commands as root - don't just prefix each individual
-# command with sudo, or you will probably install jupyter into the wrong
-# location!
-#
-# One further complication - once you have become root, $FSLDIR may not be set,
-# so either set it as we have ione below, or make sure that it is set, before
-# proceeding.
-sudo su
-export FSLDIR=/usr/local/fsl
-source $FSLDIR/fslpython/bin/activate fslpython
+# .
+# see instructions above
+# .
 conda install jupyter
 pip install notedown
 source deactivate
-ln -s $FSLDIR/fslpython/envs/fslpython/bin/jupyter $FSLDIR/bin/fsljupyter
+ln -s $FSLDIR/fslpython/envs/fslpython/bin/jupyter  $FSLDIR/bin/fsljupyter
 ln -s $FSLDIR/fslpython/envs/fslpython/bin/notedown $FSLDIR/bin/fslnotedown
 ```
 
+`notedown` is a handy tool which allows you to convert a markdown (`.md`) file
+to a Jupyter notebook (`.ipynb`) file. So you can write your practical in your
+text editor of choice, and then convert it into a notebook, instead of writing
+the practical in the web browser interface. If you install notedown as
+suggested in the code block above, you can run it on a markdown file like so:
 
-> [`notedown`](https://github.com/aaren/notedown) is a handy tool which allows
-> you to convert a markdown (`.md`) file to a Jupyter notebook (`.ipynb`)
-> file. So you can write your practical in your text editor of choice, and
-> then convert it into a notebook, instead of writing the practical in the web
-> browser interface. If you install notedown as suggested in the code block
-> above, you can run it on a markdown file like so:
->
-> ```
-> fslnotedown my_markdown_file.md > my_notebook.ipynb
-> ```
-
-
-Now you can start the notebook server from the repository root:
 
 ```
-fsljupyter notebook
+fslnotedown my_markdown_file.md > my_notebook.ipynb
 ```

advanced_topics/README.md

+Advanced Python
+===============
+
+This directory contains a collection of practicals, each of which covers a
+particular feature of the Python Programming language. They are intended for
+people who are familiar with the basics of Python, and want to learn about
+some of the more advanced features of the language.
+
+Practicals on the following topics are available:
+
+* Function inputs and outputs
+* Modules and packages
+* Object-oriented programming
+* Operator overloading
+* Decorators
+* Context managers