Started on HowTo

Author: ntoll

en/about.html

@@ -4,8 +4,8 @@
 i18n: en
 ---
 <h1>About Mu</h1>
-<p class="lead">Mu is a Python code editor for beginner programmers and based
-upon <a href="/en/discuss">feedback</a> given by teachers and learners.</p>
+<p class="lead">Mu is a Python code editor for beginner programmers based
+on extensive <a href="/en/discuss">feedback</a> given by teachers and learners.</p>
 
 <div class="row text-center">
     <a class="btn btn-lg btn-success" href="/en/download" role="button">Download</a>

en/howto/copy_files_microbit.md

@@ -0,0 +1,44 @@
+---
+layout: default
+title: How to copy files on and off a micro:bit
+i18n: en
+---
+# How to Copy Files On and Off a micro:bit
+
+MicroPython on the BBC micro:bit has [a very small filesystem](https://microbit-micropython.readthedocs.io/en/latest/tutorials/storage.html).
+Often you'll want to copy small files onto the device, or copy them from the
+micro:bit onto your own computer for further processing.
+
+Happily, Mu has a visual way to do this by dragging and dropping files. Click
+on the button shown below:
+
+<div class="row">
+  <img src="/img/en/howto/microbit_files.png" alt="Files button" class="img-responsive center-block img-rounded movie"/>
+</div>
+
+The pane shown below will appear at the bottom of Mu's window. Simply click and
+drag a file between the list of files on the micro:bit and those on your
+computer (as the animation shows). The files on your computer can be found in
+the folder Mu uses as your working directory (see the tutorial called
+[where are my files?](/en/tutorials/1.0/files)).
+
+<div class="row">
+  <img src="/img/en/howto/microbit_files.gif" alt="Moving files with a micro:bit" class="img-responsive center-block img-rounded movie"/>
+  <br/>
+</div>
+
+<div class="panel panel-danger">
+    <div class="panel-heading"><h3 class="panel-title">
+    <strong>WARNING:</strong> Don't toggle files off while the micro:bit is
+    busy!</h3></div>
+    <div class="panel-body"><p>If you click the "Files" button while the
+    micro:bit is still reacting to instructions from Mu (such as listing files,
+    getting the content of a file, and so on), then you may find that
+    afterwards the REPL behaves strangely.</p>
+    <p>The solution is simply to press restart on the device while the "Files"
+    or "REPL" panes are off.</p>
+    <p>If in doubt while using the "Files" pane, just wait for Mu to confirm
+    that whatever file related activity is happening, is reported as finished
+    (as shown above).</p>
+    </div>
+</div>

en/howto/create_load_save.md

@@ -0,0 +1,40 @@
+---
+layout: default
+title: How to create, load and save files in Mu.
+i18n: en
+---
+# How to create, load and save files in Mu
+
+You need to understand what each of the following three buttons do:
+
+<div class="row">
+  <img src="/img/en/howto/create_load_save.png" alt="New, Load and Save buttons" class="img-responsive center-block img-rounded movie"/>
+</div>
+
+* **New** - Click on this button to create a new empty file. Before you can run
+  your code you'll need to save it (i.e. give it a filename).
+* **Load** - When you click this button a file selector dialog box pops up and
+  you should click on the Python file you'd like to load into Mu (or press
+  cancel).
+* **Save** - Clicking this button saves the file in the currently selected tab.
+  If the file was newly created then Mu will ask you for a name for the file.
+
+<div class="panel panel-info">
+    <div class="panel-heading"><h3 class="panel-title">Copy/Rename Files</h3></div>
+    <div class="panel-body">
+        <p>If you want to create a newly named copy of the current file you
+        can rename it by clicking on the filename in the file's tab in Mu.</p>
+    </div>
+</div>
+
+<div class="panel panel-danger">
+    <div class="panel-heading"><h3 class="panel-title">Don't Use Python Module Names</h3></div>
+    <div class="panel-body">
+        <p>It's tempting to name your new file that uses the <code>turtle</code>
+        module as "turtle.py". <strong>Don't do this!</strong> If you name
+        your file after a module you're using <strong>in your code</strong>
+        then Python will break because it's trying to import
+        <strong>your</strong> code rather than the code from Python's standard
+        library!</p>
+    </div>
+</div>

en/howto/index.html

@@ -12,23 +12,19 @@ <h1>How-to Guides</h1>
 <h2>Installation</h2>
 
 <ul>
-    <li>How to install Mu with Python packaging on Windows, OSX and Linux.</li>
-    <li>How to install Mu on a Raspberry Pi.</li>
-    <li>How to install Mu on Windows with the official installer.</li>
-    <li>How to install Mu on OSX with homebrew.</li>
-    <li>How to install Mu on a Debian based Linux (e.g. Raspbian).</li>
-    <li>How to install Mu on a Fedora based Linux.</li>
+    <li><a href="install_windows">How to install Mu on Windows with the official installer</a>.</li>
+    <li><a href="install_with_python">How to install Mu with Python packaging on Windows, OSX and Linux</a>.</li>
+    <li><a href="install_raspberry_pi">How to install Mu on a Raspberry Pi</a>.</li>
 </ul>
 
 <h2>Using Mu</h2>
 
 <ul>
-    <li>How to create, load and save files in Mu.</li>
-    <li>How to change modes in Mu.</li>
-    <li>How to read the logs in Mu.</li>
-    <li>How to use the REPL in Python 3.</li>
-    <li>How to use the plotter.</li>
-    <li>How to copy files on and off a micro:bit.</li>
+    <li><a href="create_load_save">How to create, load and save files in Mu</a>.</li>
+    <li><a href="read_logs">How to read the logs in Mu</a>.</li>
+    <li><a href="copy_files_microbit">How to copy files on and off a micro:bit</a>.</li>
+    <li>How to configure Python3 to work with GPIOZero.</li>
+    <li>How to minify your MicroPython scripts for the micro:bit.</li>
     <li>How to add new sounds and images to Pygame Zero.</li>
 </ul>
 

en/howto/install_raspberry_pi.md

@@ -0,0 +1,20 @@
+---
+layout: default
+title: How to install Mu on a Raspberry Pi
+i18n: en
+---
+
+# How to install Mu on a Raspberry Pi
+
+If you're using the Raspberry Pi Foundation's official
+[Raspbian](https://www.raspberrypi.org/downloads/raspbian/)
+operating system you should use your preferred package management application
+and install `mu-editor`.
+
+If you're familiar with a terminal it's as simple as typing:
+
+```
+apt-get install mu-editor
+```
+
+Mu should be accessible from the desktop's menu.

en/howto/install_windows.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: How to install Mu on Windows with the Official Installer
+i18n: en
+---
+
+# How to install Mu on Windows with the Official Installer 
+
+Since most of our users will be using Mu on Windows in an educational setting
+we've made it extraordinarily easy to install Mu on Windows. We've checked
+Mu works on Windows 7 (32bit) and Windows 10 (64bit) - so it should work on
+all the versions of Windows in between.
+
+First, follow the
+[advice on Microsoft's website](https://support.microsoft.com/en-us/help/15056/windows-7-32-64-bit-faq) to work out if you're using 32 or 64 bit Windows.
+
+Next, [download the correct installer](/en/download) for your version of
+Windows (either 32 or 64 bit for Windows 7 or above). The installer itself is
+an executable so you need to run it to make it work.
+
+Follow the steps illustrated below and, once installation has finished, you'll
+find Mu in your start menu.
+
+<div class="row">
+  <h2>Step 1</h2>
+  <p>Confirmation of the version of Mu you'll be installing. The version
+  number will likely be different from the one shown below.</p>
+  <img src="/img/en/howto/winstall1.png" alt="Windows installer step 1" class="img-responsive center-block img-rounded movie"/>
+</div>
+<div class="row">
+  <h2>Step 2</h2>
+  <p>You need to agree to <a href="https://github.com/mu-editor/mu/blob/master/LICENSE">Mu's license</a> before installing the software.</p>
+  <img src="/img/en/howto/winstall2.png" alt="Windows installer step 2" class="img-responsive center-block img-rounded movie"/>
+</div>
+<div class="row">
+  <h2>Step 3</h2>
+  <p>Select if you want to install Mu for all users, or just yourself.</p>
+  <img src="/img/en/howto/winstall3.png" alt="Windows installer step 3" class="img-responsive center-block img-rounded movie"/>
+</div>
+<div class="row">
+  <h2>Step 4</h2>
+  <p>Select the installation destination (you can usually safely ignore this
+  step).</p>
+  <img src="/img/en/howto/winstall4.png" alt="Windows installer step 4" class="img-responsive center-block img-rounded movie"/>
+</div>
+<div class="row">
+  <h2>Step 5</h2>
+  <p>Go make a cup of coffee as Mu installs on your machine.</p>
+  <img src="/img/en/howto/winstall5.png" alt="Windows installer step 5" class="img-responsive center-block img-rounded movie"/>
+</div>
+<div class="row">
+  <h2>Step 6</h2>
+  <p>Confirmation that Mu has installed properly.</p>
+  <img src="/img/en/howto/winstall6.png" alt="Windows installer step 6" class="img-responsive center-block img-rounded movie"/>
+</div>

en/howto/install_with_python.md

@@ -0,0 +1,88 @@
+---
+layout: default
+title: How to install Mu with Python packaging on Windows, OSX and Linux.
+i18n: en
+---
+# How to install Mu with Python packaging on Windows, OSX and Linux
+
+If you already have [Python3](https://python.org/) installed on your Windows,
+OSX or Linux machine then the easiest way to install Mu is with Python's
+built-in package manager, [`pip`](https://pip.pypa.io/en/stable/installing/).
+If you're on Windows and would rather not type commands you should use the
+[Windows installer for Mu](install_windows) instead.
+
+At your OS's command prompt (see below) type the following command:
+
+```
+pip3 install mu-editor
+```
+
+You'll see a bunch of things downloading from the internet. These are the other
+Python libraries Mu needs to work. If it's worked the final message from `pip`
+will be something like, "Successfully installed..." followed by a list of all
+the packages upon which Mu depends.
+
+To run Mu, still in the command prompt, type:
+
+```
+mu-editor
+```
+
+Press return and the editor should launch.
+
+<div class="panel panel-danger">
+    <div class="panel-heading"><strong>Warning</strong></div>
+    <div class="panel-body"><p>Depending on how <strong>your</strong> machine
+    is set up, you may encounter errors. The most common are:</p>
+    <ul>
+        <li>You don't have permission to use <code>pip</code> to install
+        packages, in which case, talk to whoever administers your computer and
+        ask them to install Mu for you (just point them to this website).</li>
+        <li>You're using the wrong or and old version of <code>pip</code>. If
+        you have Python 2 installed on your machine, you <strong>must</strong>
+        make sure you're using <code>pip3</code>. If <code>pip</code> complains
+        it is out of date, follow these
+        <a href="https://pip.pypa.io/en/stable/installing/">instructions for
+        updating pip</a>.</li>
+        <li>You can't even run <code>pip</code>, in which case check you have
+        Python 3 installed and that when Python was installed, you clicked the
+        option that asks you if you'd like Python added to your path (you
+        do).</li>
+    </ul>
+    <p>If you're still facing problems, perhaps try using another installation
+    method (HINT: if you're on Windows, use the Windows installer instead).
+    As a last resort why not see if anyone can help you in the
+    <a href="/en/discuss">discussions</a>.</p>
+    </div>
+</div>
+
+## What is a Command Prompt?
+
+Most people use a graphical user interface (GUI) on their computer: basically,
+windows and icons controlled with a mouse and pointer. However, it's also
+possible to control your computer by typing commands into a prompt. Once you
+know the commands, this is often the most powerful way to use a computer.
+However, it can feel a bit like casting spells with incomprehensible
+incantations so may, at first, appear frightening.
+
+Find your computer's command prompt depends upon which operating system you're
+using:
+
+* Windows: in the search area of your start menu, type `cmd` and
+  press enter.
+* Mac OSX: use the finder to go to the Applications folder and then the
+  Utilities folder. Open the "Terminal" app.
+* Linux: look for the "Terminal" app in your desktop's menu.
+
+## I Want a Shortcut!
+
+When `pip` installs software it doesn't automatically create a shortcut or menu
+item for you. Happily, someone has created a utility called `shortcut` to do
+this for you.
+
+Simply use `pip` to install `shortcut` and then use `shortcut` on Mu:
+
+```
+pip3 install shortcut
+shortcut mu
+```

en/howto/read_logs.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: How to read the logs in Mu.
+i18n: en
+---
+# How to read the logs in Mu
+
+Log files are a way for Mu to keep track of what it has been doing. These is
+**very** useful when trying to work out why Mu has behaved in a certain way or
+if Mu has encountered an error. Logs also help work out how students may have
+got Mu into a certain undesirable state.
+
+In any case, Mu keeps up to 5 days worth of logs in the user's directory the
+operating system defines for such things. Since this directory changes from
+system to system and may even depend on the way in which a computer is
+configured (for example, user data is stored on a network drive), Mu provides a
+shortcut to the *current log file*: click on the small cog icon in the bottom
+right hand side of Mu, right next to the name of the current mode.
+
+Mu **appends** lines to the log file, so the most recent line is at the end of
+the logs.
+
+Every time Mu starts it logs details about the system, including the paths to
+the various places it stores things such as log files, settings and sessions.
+This will look something like:
+
+```
+-----------------
+
+Starting Mu 1.0.0.beta.15
+2018-03-19 16:51:22,385 - root:95(run) INFO: uname_result(system='Linux', node='heraclitus', release='4.13.0-36-generic', version='#40-Ubuntu SMP Fri Feb 16 20:07:48 UTC 2018', machine='x86_64', processor='x86_64')
+2018-03-19 16:51:22,448 - mu.logic:499(__init__) INFO: Setting up editor.
+2018-03-19 16:51:22,449 - mu.logic:510(__init__) INFO: Settings path: /home/ntoll/.local/share/mu/settings.json
+2018-03-19 16:51:22,449 - mu.logic:511(__init__) INFO: Session path: /home/ntoll/.local/share/mu/session.json
+2018-03-19 16:51:22,449 - mu.logic:512(__init__) INFO: Log directory: /home/ntoll/.cache/mu/log
+2018-03-19 16:51:22,449 - mu.logic:513(__init__) INFO: Data directory: /home/ntoll/.local/share/mu
+2018-03-19 16:51:22,467 - mu.logic:521(setup) INFO: Available modes: python, adafruit, microbit, debugger, pygamezero
+2018-03-19 16:51:22,518 - mu.logic:856(change_mode) INFO: Workspace directory: /home/ntoll/mu_code
+2018-03-19 16:51:22,519 - mu.logic:560(restore_session) INFO: Restoring session from: /home/ntoll/.local/share/mu/session.json
+```
+
+Each time Mu restarts it emits a line like this: `-----------------`. This
+makes it easy to visually find restarts in the log file.
+
+Each line in the log file follows a pattern:
+
+* It starts with the date and time of the log entry, YYYY-MM-DD HH:MM:SS
+* Next comes the name of the file and the line number that generated the log
+  entry.
+* Following this, in parenthesis, is the name of the function being evaluated
+  when the log entry was created.
+* Next comes an indication of the type of log entry this is. This will be one
+  of the following values: `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`.
+  See the [Python documentation on logging](https://docs.python.org/3.6/library/logging.html#logging-levels) for what they mean.
+* Finally, you'll see some sort of textual output, often a helpful message
+  explaining why the log was written, or perhaps a copy of some data which Mu
+  was processing at the time of the log entry.
+
+If you ever find a bug in Mu, please attach a **complete** copy of the log file
+for the day when you discovered the bug (and it'd be helpful if you point out
+the lines in the log for when the bug was encountered).