Skip to content

Commit f3ed6bf

Browse files
ntollntoll
committed
All pages complete. TODO: Check / revise. Updated help to be more friendly.
1 parent d82b54d commit f3ed6bf

22 files changed

+909
-26
lines changed

‎en/help/1.0.md

Lines changed: 50 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,54 @@ title: Help for Mu 1.0.*
55

66
# Help for Mu 1.0
77

8-
You have three options for finding help about this version of Mu:
8+
<div class="row">
9+
<div class="col-sm-4 col-md-4">
10+
<div class="thumbnail">
11+
<a href="/en/tutorials">
12+
<img src="/img/en/tutorials/start.gif" alt="Tutorials"
13+
class="img-responsive center-block img-rounded movie-light">
14+
</a>
15+
<div class="caption">
16+
<h3>1. Tutorials</h3>
17+
<p>All the basics you need to know to get started and help with first
18+
steps in using Mu. <strong>If you only read one thing, make it
19+
this!</strong></p>
20+
<p><a href="/en/tutorials" class="btn btn-primary"
21+
role="button">Go</a> Level: <strong>SUPER EASY</strong></p>
22+
</div>
23+
</div>
24+
</div>
25+
<div class="col-sm-4 col-md-4">
26+
<div class="thumbnail">
27+
<a href="/en/howto">
28+
<img src="/img/en/help/howto.png" alt="Howto"
29+
class="img-responsive center-block img-rounded movie-light">
30+
</a>
31+
<div class="caption">
32+
<h3>2. How-to Guides</h3>
33+
<p>These deal with common tasks or problems in a simple
34+
step-by-step manner. If you're looking for something specific,
35+
look here.</p>
36+
<p><a href="/en/howto" class="btn btn-primary"
37+
role="button">Go</a> Level: <strong>INTERMEDIATE</strong></p>
38+
</div>
39+
</div>
40+
</div>
41+
<div class="col-sm-4 col-md-4">
42+
<div class="thumbnail">
43+
<a href="/en/discuss">
44+
<img src="/img/en/help/chat.png" alt="Chat"
45+
class="img-responsive center-block img-rounded movie-light">
46+
</a>
47+
<div class="caption">
48+
<h3>3. Discussion Channel</h3>
49+
<p>Our web-based chat-room is where you can ask questions or discuss
50+
My with both other users and the developers of Mu.</p>
51+
<p><a href="/en/discuss" class="btn btn-primary"
52+
role="button">Go</a> Level: <strong>ADVANCED-ish</strong></p>
53+
</div>
54+
</div>
55+
</div>
56+
</div>
957

10-
1. The [tutorials](/en/tutorials) introduce you to using Mu.
11-
They are the best place to start. The tutorial entitled
12-
"[Start Here!](/en/tutorials/1.0/start)" gives you the basics needed to get
13-
going. If you follow the tutorials, one after the other, you'll very quickly
14-
become an expert in using Mu (the tutorials themselves are *very easy* to
15-
follow).
16-
2. The [how-to guides](/en/howto/) deal with common tasks or problems in a
17-
simple step-by-step manner. If you're looking for something specific then
18-
look here.
19-
3. The [discussion channel](/en/discuss) is a web based chat-room for members
20-
of the Mu community. We expect participants to follow the Python Software
21-
foundation's [Code of Conduct](https://www.python.org/psf/codeofconduct/).
22-
The discussion channel is where you can ask questions or discuss Mu with
23-
both other users and the developers of Mu.
24-
25-
Finally, if you think you've found a bug in Mu then [follow the steps outlined here](/en/howto/bugs).
58+
**If you think you've found a bug in Mu, congratulations! Please [follow the steps outlined here](/en/howto/bugs).**

‎en/tutorials/1.0/configuration.md

Lines changed: 35 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,43 @@
11
---
22
layout: default
3-
title: Configuration
3+
title: Advanced Configuration
44
i18n: en
55
---
66

7-
# Configuration
7+
# Advanced Configuration
88

9-
Session file vs settings file.
9+
There's nothing advanced about configuring Mu -- you just edit a couple of
10+
files. To find the relevant files you need to check the logs and make a note
11+
of the paths to the files: `settings.json` and `session.json` (see the example
12+
shown below).
1013

11-
Settings:
14+
<div class="row">
15+
<img src="/img/en/tutorials/settings_location.png" alt="Settings files" class="img-responsive center-block img-rounded movie"/>
16+
<br/>
17+
</div>
1218

13-
* `microbit_runtime_hex` -
14-
* `workspace` -
19+
The `session.json` file contains details of Mu's state when you last quit the
20+
editor. It means you can restart Mu where you left off. Mu always overwrites
21+
the content of this file so it's not particularly useful for configuring Mu.
22+
However, it could be a source of useful information when trying to work out
23+
what Mu thinks it should be doing.
24+
25+
The `settings.json` file is currently used to one "global" setting: the
26+
directory on the user's filesystem in which users should save their files. As
27+
requirements change, more settings may be added to later versions. Each user
28+
of the computer will have their own `settings.json` file.
29+
30+
If no setting is given, Mu defaults to the `mu_code` directory in the current
31+
user's default home directory (as reported by the host operating system).
32+
33+
To change the default to something else, you'll need to update the
34+
`settings.json` file to something like this:
35+
36+
```
37+
{
38+
"workspace": "/home/ntoll/src"
39+
}
40+
```
41+
42+
The path to the new `workspace` value must be a valid path to a directory that
43+
already exists. Otherwise, Mu will ignore it.

‎en/tutorials/1.0/debugger.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
layout: default
3+
title: The Visual Debugger
4+
i18n: en
5+
---
6+
7+
# The Visual Debugger
8+
9+
Have you ever wanted to look over the shoulder of Python as it was running
10+
your code? It's a useful ability because you get to compare how you *think*
11+
your code is run with how Python *actually* runs it. This is extraordinarily
12+
helpful if you're trying to find bugs.
13+
14+
This is what Mu's simple visual debugger allows you to do with Python 3 code.
15+
16+
The functionality provided by the debugger happens in three places.
17+
18+
First of all, while in Python 3 mode or when the debugger is running, it's
19+
possible to indicate where Python should pause execution of your script
20+
(giving you an opportunity to look around at that point). This is done with a
21+
breakpoint, indicated by a circle in the margin next to the line-numbers and
22+
toggled on and off by clicking the line number of the desired line. In the
23+
picture below, there's a breakpoint set on line 4, and the debugger will run
24+
your code up until this line, at which point, it will pause:
25+
26+
<div class="row">
27+
<img src="/img/en/tutorials/breakpoint.png" alt="A breakpoint" class="img-responsive center-block img-rounded movie"/>
28+
<br/>
29+
</div>
30+
31+
Secondly, when you click the "Debug" button, two things will happen: your
32+
code will be run under the control of the debugger (as a result, it takes
33+
a little longer than normal for your code to start running), and the buttons
34+
associated with the Python 3 mode will be replaced with the following new
35+
buttons that allow you to navigate your code:
36+
37+
<div class="row">
38+
<img src="/img/en/tutorials/debug_buttons.png" alt="The Visual Debugger buttons" class="img-responsive center-block img-rounded movie"/>
39+
<br/>
40+
</div>
41+
42+
Finally, while the debugger is running the inspector pane will appear on the
43+
right hand side and list all the objects Python knows about at that moment in
44+
the execution of your script, along with their associated value. This allows
45+
you to see into the current state of your program and check things are as you
46+
expect them to be.
47+
48+
<div class="row">
49+
<img src="/img/en/tutorials/debug_inspector.png" alt="The debug inspector" class="img-responsive center-block img-rounded movie"/>
50+
<br/>
51+
</div>
52+
53+
Just like when you "Run" a program, a new pane will appear below the code area
54+
and above the footer. This will contain any textual input and output for your
55+
program.
56+
57+
<div class="panel panel-warning">
58+
<div class="panel-heading"><strong>Code is Read-Only when Debugging</strong></div>
59+
<div class="panel-body">
60+
<p>To avoid the potential for confusion, when the debugger is running,
61+
you won't be able to change your code. This is because Python's
62+
debugger runs your program <em>as it existed when you clicked the
63+
"Debug" button</em>. If you were able to change it after this point,
64+
there is a possibility that the code the debugger highlights in your
65+
code area doesn't actually exist in the running program.</p>
66+
</div>
67+
</div>
68+
69+
If you click the "Debug" button without having first set some breakpoints then
70+
the debugger will pause on the first available line.
71+
72+
In any case, once the debugger has control of your program, it will
73+
highlight the line in your code that Python is about to execute, update the
74+
inspector with the names and values of all the things it curretly knows about
75+
and wait for you to do something. At this point you can use the buttons to
76+
navigate your code.
77+
78+
The "Stop" button does what you expect: the debugger stops and you're returned
79+
to Python 3 mode.
80+
81+
The "Continue" button will run your code until either the next breakpoint is
82+
reached (at which point, the debugger will pause again) or your program
83+
finishes.
84+
85+
The "Step Over" button moves forward through your code one line at a time, no
86+
matter if there is or isn't a breakpoint on the next line. It means you can
87+
watch as each individual line of code effects the state of your program.
88+
89+
Sometimes the debugger will highlight a line that calls a function. If you were
90+
to "Step Over" this line then you'll move onto the next line without seeing
91+
what the function was doing. But what if you
92+
wanted to step into the function that was called, to see what that block of
93+
code did? Well, that's the purpose of the "Step In" button. Instead of
94+
moving onto the next line in the *current* block of code, it'll skip
95+
into the function and highlight the first block of code *in the function*.
96+
97+
Of course, you may find yourself in a function which isn't very interesting and
98+
you just want to move back to the line of code that called it (rather than
99+
having to keep pressing "Step Over" until you got to the end of the function).
100+
Happily, this is exactly what the "Step Out" button does: if you're in a
101+
function, it'll move to the line of code immediately *after* the line that
102+
called the current function.
103+
104+
All these sorts of interactions are illustrated below.
105+
106+
<div class="row">
107+
<img src="/img/en/tutorials/debugger.gif" alt="The Visual Debugger" class="img-responsive center-block img-rounded movie"/>
108+
<br/>
109+
</div>

‎en/tutorials/1.0/logs.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
layout: default
3+
title: Log Files and Configuration
4+
i18n: en
5+
---
6+
7+
# Log Files and Configuration
8+
9+
Sometimes you need to know more about what Mu is doing, in which case you
10+
should check the log files.
11+
12+
Sometimes you need to let Mu know it should modify its behaviour, in which case
13+
you should configure some simple (yet powerful) settings.
14+
15+
To access both you should click on the small cog icon in the bottom right of
16+
Mu's window:
17+
18+
<div class="row">
19+
<img src="/img/en/howto/cog_button.png" alt="The cog button" class="img-responsive center-block img-rounded movie"/>
20+
<br/>
21+
</div>
22+
23+
This opens a new dialog window containing three tabs.
24+
25+
The first tab contains the logs written during the current day:
26+
27+
<div class="row">
28+
<img src="/img/en/howto/log_window.png" alt="The log tab" class="img-responsive center-block img-rounded movie"/>
29+
<br/>
30+
</div>
31+
32+
To learn what the log entries mean please read our guide for
33+
[how to read logs in Mu](/en/howto/read_logs).
34+
35+
The second tab allows you to configure various aspects of the environment in
36+
which Python 3 runs your code (so called "environment variables"):
37+
38+
<div class="row">
39+
<img src="/img/en/howto/envars.png" alt="The envar tab" class="img-responsive center-block img-rounded movie"/>
40+
<br/>
41+
</div>
42+
43+
To learn how to update the Python 3 environment with environment variables,
44+
read our guide for [how to do this](/en/howto/python3_envars).
45+
46+
Finally, the third tab contains various settings for flashing code onto a
47+
connected BBC micro:bit:
48+
49+
<div class="row">
50+
<img src="/img/en/howto/microbit_settings.png" alt="The micro:bit tab" class="img-responsive center-block img-rounded movie"/>
51+
<br/>
52+
</div>
53+
54+
To learn how to change the way code is flashed onto a connected BBC micro:bit,
55+
read our guide for [how to do this](/en/howto/microbit_settings).

‎en/tutorials/1.0/moving-on.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
layout: default
3+
title: Moving on from Mu
4+
i18n: en
5+
---
6+
7+
# Moving on from Mu
8+
9+
Mu was created to help you take your first steps in programming with Python.
10+
We want you to learn all you can with Mu, but there will come a time when you
11+
need to graduate to a more advanced code editor.
12+
13+
Here are some suggestions for what to explore next:
14+
15+
* [Jupyter Notebooks](https://jupyter.org/) are an amazing way to create an
16+
interactive narrative with code, multi-media and traditional prose. The
17+
REPL in Python 3 mode is a simplified version of a Jupyter notebook, so
18+
project Jupyter should immediately feel familiar. They also have a
19+
wonderfully friendly community.
20+
* [Atom](https://atom.io/) is a free and simple code editor with lots of
21+
useful *optional* features. Made by the folks at GitHub, it works with many
22+
different programming languages and on all the platforms supported by Mu.
23+
* [Visual Studio Code](https://code.visualstudio.com/) is a powerful yet easy
24+
to use cross platform code editor for many different programming languages.
25+
Microsoft have done a great job in supporting Python and
26+
you'll find it comes with more advanced versions of all the features of Mu.
27+
* [PyCharm](https://www.jetbrains.com/pycharm/) is advertised as a Python
28+
IDE (integrated development environment -- i.e. it has lots of bells and
29+
whistles) for professional developers. Apparently there is a simplified
30+
educational version, although I've heard mixed reviews from teachers about
31+
how good it is.
32+
33+
Finally, please remember that creating software is a collaborative process.
34+
Be open to the ideas of others, show respect for their time, efforts and
35+
feelings and be considerate to your peers.
36+
37+
Good luck! :-)

0 commit comments

Comments
 (0)