Merge pull request #59 from innovationOUtside/wip

ipynb conversion

content/00_FOR_VLE/.X/X-Section_00_02_Workload.md

@@ -0,0 +1,18 @@
+## 1.2 Workload
+
+The RoboLab practical sessions have been written so that if you are an absolute beginner with no experience of robotics or programming you can complete the work each week in four to five hours. The pace is deliberately unhurried and we recommend you take your time. If you already have some programming experience RoboLab should take you less time.
+
+Each week’s practical session combines two aspects of robotics. We will teach you the basics of programming in RoboLab, introducing features gradually during the sessions. You will also carry out some investigations using the simulated robot which will give you a taste of some of the more practical aspects of robotics.
+
+Throughout the RoboLab sessions you may encounter a number of activities that are labelled as ‘challenges’. We’ve defined these tasks as challenges because:
+
+- there may be several ways of achieving a solution to the task, rather than a single best approach
+
+- it may be possible to refine any particular solution and improve its performance.
+
+Challenges implicitly incorporate some performance measure that you can use to rate the effectiveness of your solution, such as the time taken for the robot to complete a task, or the accuracy with which it does so. There is thus a mildly competitive element to the activity. You may not get the chance to compare your solution with those of other students, but you can think about trying to improve the quality of your own solution – though you should not spend too long trying for perfection!
+
+
+### Assessment
+
+We hope that by the end of the RoboLab practical sessions you understand some of the basic ideas and can program the simulated robot to do some basic tasks. This should ensure that you can do the assignment and complete the block satisfactorily. The assessment will not include any material covered in optional practical activities.

content/00_FOR_VLE/.X/X-Section_00_03_Accessibility.md

@@ -0,0 +1,72 @@
+## 1.3 Accessibility
+
+We have tried our best to make RoboLab accessible to all students, whatever their particular needs.
+
+__TO DO - I havenlt test accessibility toolbar in conjucntion with the simulator; they may or may not play well together...__
+
+The Jupyter environment includes an [accessibility toolbar extension](https://github.com/uclixnjupyternbaccessibility/accessibility_toolbar) that allows you to control the presentation style of the Jupyter notebook; for example, you can change the font style, size and spacing, the notebook background colour, and so on. Several predefined custom themes are available [BROKEN] and you can also define your own. The extension also supports voice control [BROKEN].
+
+__TO DO: there is also a [jupyter-themes](https://github.com/dunovank/jupyter-themes) extension that we could pre-install, perhaps with one or more OU custome themes? This may be in addtion to, or in place of, the accessibility toolbar. There are also simple tricks and tools for speaking out code cell contents, such as the [jupyter-a11y](https://github.com/jameslmartin/jupyter-a11y) extension.__
+
+All of the styles are saved into local storage when refreshing the page. This means that if you use notebooks on different servers with the same browser, the same accessibility settings will be applied to notebooks on all servers within which you have enabled the accessibilty extension.
+
+
+### Enabling the Accessibility Extension
+The accessibility is __disabled__ in the RoboLab environment by default. To use the accessibility extension, you need to enable it first. You can do this from the `nbextensions` tab on the notebook homepage: check the `Accessibility toolbar` extension to enable the toolbar. When you open a new notebook, the toolbar should be displayed.
+
+![Screenshot of the nbextensions confgurator showing the location of the Accessibility Toolbar.](../images/00_01_nb_extensions_accessibility.png)
+
+Check the [accessibility toolbar documentation](https://github.com/uclixnjupyternbaccessibility/accessibility_toolbar#toolbar-summary) for more information.
+
+The Module Team welcome feedback on these features.
+
+
+### Colours and fonts
+
+If you wish to change the font and interface colours used in RoboLab to improve readability, the accessibility toolbar allows you to select the font style, size and colour. You can also modify the line spacing and spacing between individual characters.
+
+![Screenshot of the colours and fonts menu dropped down from the text / A button in the group of Accessibility Toolbar buttons.](../images/00_01_accessibility_display.png)
+
+The font style applies to *all* text elements within the notebook itself. This includes the contents of markdown (text) cells, code cells and code cell outputs.
+
+The toolbar can also be used to control the notebook's background colour and the cell background colour.
+
+You can also save a style you have defined from the `Add new style...` option in `Predefined styles` menu. Once saved, it will be added to the menu list so you can apply it as required. 
+
+
+### Keyboard interface
+
+The Jupyter notebook interface supports a wide range of pre-defined keyboard shortcuts to menu and toolbar options. The shortcuts can be displayed using the `Keyboard shortcuts` item from the notebook `Help` menu or via the `ESC-h` keyboard shortcut.
+
+![Screenshot of the Jupyter keyboard shortcuts help page previewing the Command Mode cell options.](../images/00_01_jupyter_nb_shortcuts.png)
+
+You can also add additional shortcuts and/or edit exist shortcuts via the `Edit Keyboard shortcuts` menu item.
+
+![Screenshot of the Jupyter keyboard shortcuts help page previewing the Edit Command Mode cell options.](../images/00_01_jupyter_nb_edit_shortcuts.png)
+
+__TO DO: is Jyro keyboard accessible??__
+
+__TO DO: what's best way of tabbing through the notebook? Or should notebook keyboard shortcuts be used? Are any potentially useufl navigation style keyboard shortcuts missing?__
+
+
+### Magnification
+
+The apparent size of the notebook contents in general can be zoomed using standard browser magnification tools. 
+
+Alternatively, use operating systems tools such as *Windows Magnify* or the MacOS *Zoom Window*, or other assistive software.
+
+
+### Other assistive software
+
+__TO DO: to what extent will screen readers and dictation systems operate features of RoboLab??__
+
+Please contact the Module Team if you discover that the material does not work with a particular screen reader or dictation system that you would typically expect to be able to use.
+
+
+### Audio
+
+Some RoboLab programs 'speak'. Where the speech is generated as a part of a program flow, a visual display of the spoken phrase will also typically be displayed at the time the phrase is spoken.
+
+__TO DO: https://github.com/jameslmartin/jupyter-a11y/ accessibility extension which included keyboard shortcuts to read the highlighted cell, cancel reading of the cell, skip the current line of the code cell being read widget. I will update this extension, try it out and if it works okay add it to the environment.
+
+__TO DO: need to make sure we do this; a custom widget might help that maps to both audio and a text display widget._

content/00_FOR_VLE/.X/X-Section_00_04_Writing_Code.md

@@ -0,0 +1,55 @@
+<!-- #region -->
+## 1.4 Writing Style Compliant Code
+
+__NOTE TO CRITICAL READERS: THIS IS INTENDED AS GENERIC TO JUPYTER ENVTS AND AIMS TO NUDGE STUDENTS TOWARDS GOOD CODE STYLE PRACTICE IF THEY WANT NUDGING.__
+
+Whilst this is not specifically a programming course, this may well be the first time you have done any sort of programming at all, let alone any programming in Python.
+
+The style of programming we are teaching is geared towards helping you understand how we might be able to control robots through programme code, rather than formally teaching you programming in general, or Python coding in particular.
+
+However, we will try to to demonstrate code examples that are well written and that comply with the popular [PEP 8 — Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/). This guide sets out a set of stylistic convention for writing clear Python code.
+
+There are many tools available that can be used to support code authors and we have installed some of them into the RoboLab environment.
+
+One particular tool is know as a "linter". Linters can post warnings about where the code diverges from PEP-8 guidelines.
+
+Error codes are described via the following links:
+
+- `E*`, `W*`: [show code lookups](https://pycodestyle.readthedocs.io/en/latest/intro.html#error-codes);
+- `D*`: [show code lookups](http://www.pydocstyle.org/en/2.1.1/error_codes.html);
+- `F*`: [show code lookups](http://flake8.pycqa.org/en/3.7.9/user/error-codes.html).
+
+
+In the notebooks, you will be writing code:
+
+- intended to be downloaded and run in the simulator;
+- that runs in a Python environment associated with the notebook.
+
+At the moment, if linting is enabled, it will only be applied to code that is intended to run in the notebook's Pyhton environment, not for code that is intended to be downloaded to the simulator environment.
+
+__TO DO: I am looking to see if I can lint everything.__
+
+The linter can be enabled in a notebook by running the following magic:
+
+`%flake8_on --ignore D100`
+
+__TO DO: flake seems to be broken atm tho pycodestyle ok; also note probably only works with native code cells, not magic ones, though I may be able to fix that by tweaking magic to ignore the `%%sim_magic` call...__
+
+When you run a code cell, if the linter detects a difference from the style guide, it will display a warning of the form:
+
+TO DO 
+
+??show line numbers
+??fix 
+??rerun
+<!-- #endregion -->
+
+Another useful extension that is installed, but not enabled, is the `Autopep8` extension. You can enable the extension from the `nbextensions Configurator` [[direct link](/nbextensions/?nbextension=code_prettify/autopep8)]. Enabling this extension provides a "hammer" toolbar button that you can use to prettify your code in accord with some PEP-8 recommendations at least. Simply select a code select, and hit the button; it will prettify the code, if it can, in a more PEP-8 compliant way. (But it won't change the way your code executes, so it won't tend to fix bugs in your code for you...)
+
+One way of using the `flake8` linter and `Autopep8` button together is to let the linter raise a warning (if you do make an error), use the button to try to fix the code, then run the cell again to invoke the linter and see if the warning(s) were addressed. If they were, *inspect the fixed code to see what change the `Autopep8` tool made* (`CTRL-z` (Win), `CMD-z` (Mac) will undo the last cell edit; `SHIFT-CTRL-z` (Win), `SHFT-CMD-z` (Mac) will then redo it).
+
+Tools are also available to support writing markdown text in markdoan cells. For example, enabling the `livemdpreview` extension will display an inline live preview of the rendered markdown directly beneath a markdown cell as you edit it [[direct link](/nbextensions/?nbextension=livemdpreview/livemdpreview)] or via the Accessibility toolbar.
+
+
+### Spell Checking
+A spell checker is also available to check spelling in markdown cells. Enable the `spellchecker` notebook extension [[direct link](/nbextensions/?nbextension=spellchecker/main])] or the spell checker via the *Accessibility Toolbar Extension*.