From 83313e4e8f2209674f39114579b8325b7273c87e Mon Sep 17 00:00:00 2001 From: JohnGuan Date: Mon, 24 Dec 2018 23:59:56 +0800 Subject: [PATCH] Add Chinese website translation. 1. Add zh to lang_list.html . 2. Add nav_zh.html . 3. Add zh layout/theme to display Chinese CC licence. 4. Add zh\about.html translation. 5. Add zh\develops.html translation. 6. Add zh\discuss.html translation. 7. Add zh\download.md translation. 8. Remove old zh\help\1.0.html file 9. Add zh\help\1.0.md translation. 10. Add zh\howto\index.html translation. 11. Add zh\index.html translation. 12. Add zh\thanks.html translation. 13. Add zh\tutorials\index.html translation. 14. Add zh\tutorials\1.0\index.html translation. 15. Add zh\tutorials\1.0\start.md translation. --- Gemfile.lock | 39 +-- _includes/lang_list.html | 1 + _includes/nav_zh.html | 31 +++ _includes/themes/mu/zh.html | 70 ++++++ _layouts/zh.html | 6 + zh/about.html | 41 +++ zh/developers.html | 18 ++ zh/discuss.html | 30 +++ zh/download.md | 91 +++++++ zh/help/1.0.html | 11 - zh/help/1.0.md | 58 +++++ zh/help/index.md | 11 + zh/howto/bugs.md | 65 +++++ zh/howto/copy_files_microbit.md | 44 ++++ zh/howto/create_load_save.md | 41 +++ zh/howto/fix_code.md | 221 +++++++++++++++++ zh/howto/index.html | 37 +++ zh/howto/install_macos.md | 76 ++++++ zh/howto/install_raspberry_pi.md | 67 +++++ zh/howto/install_windows.md | 191 ++++++++++++++ zh/howto/install_with_python.md | 97 ++++++++ zh/howto/microbit_settings.md | 50 ++++ zh/howto/pgzero_sounds_images.md | 35 +++ zh/howto/python3_envars.md | 53 ++++ zh/howto/read_logs.md | 93 +++++++ zh/howto/think_code.md | 35 +++ zh/howto/use_portamu.md | 103 ++++++++ zh/index.html | 21 ++ zh/thanks.html | 400 ++++++++++++++++++++++++++++++ zh/tutorials/1.0/adafruit.md | 60 +++++ zh/tutorials/1.0/configuration.md | 43 ++++ zh/tutorials/1.0/debugger.md | 109 ++++++++ zh/tutorials/1.0/files.md | 39 +++ zh/tutorials/1.0/index.html | 241 ++++++++++++++++++ zh/tutorials/1.0/logs.md | 55 ++++ zh/tutorials/1.0/microbit.md | 84 +++++++ zh/tutorials/1.0/modes.md | 91 +++++++ zh/tutorials/1.0/moving-on.md | 37 +++ zh/tutorials/1.0/pgzero.md | 51 ++++ zh/tutorials/1.0/plotter.md | 108 ++++++++ zh/tutorials/1.0/problems.md | 28 +++ zh/tutorials/1.0/python.md | 87 +++++++ zh/tutorials/1.0/repl.md | 320 ++++++++++++++++++++++++ zh/tutorials/1.0/shortcuts.md | 164 ++++++++++++ zh/tutorials/1.0/start.md | 141 +++++++++++ zh/tutorials/index.html | 241 ++++++++++++++++++ 46 files changed, 3909 insertions(+), 26 deletions(-) create mode 100644 _includes/nav_zh.html create mode 100644 _includes/themes/mu/zh.html create mode 100644 _layouts/zh.html create mode 100644 zh/about.html create mode 100644 zh/developers.html create mode 100644 zh/discuss.html create mode 100644 zh/download.md delete mode 100644 zh/help/1.0.html create mode 100644 zh/help/1.0.md create mode 100644 zh/help/index.md create mode 100644 zh/howto/bugs.md create mode 100644 zh/howto/copy_files_microbit.md create mode 100644 zh/howto/create_load_save.md create mode 100644 zh/howto/fix_code.md create mode 100644 zh/howto/index.html create mode 100644 zh/howto/install_macos.md create mode 100644 zh/howto/install_raspberry_pi.md create mode 100644 zh/howto/install_windows.md create mode 100644 zh/howto/install_with_python.md create mode 100644 zh/howto/microbit_settings.md create mode 100644 zh/howto/pgzero_sounds_images.md create mode 100644 zh/howto/python3_envars.md create mode 100644 zh/howto/read_logs.md create mode 100644 zh/howto/think_code.md create mode 100644 zh/howto/use_portamu.md create mode 100644 zh/index.html create mode 100644 zh/thanks.html create mode 100644 zh/tutorials/1.0/adafruit.md create mode 100644 zh/tutorials/1.0/configuration.md create mode 100644 zh/tutorials/1.0/debugger.md create mode 100644 zh/tutorials/1.0/files.md create mode 100644 zh/tutorials/1.0/index.html create mode 100644 zh/tutorials/1.0/logs.md create mode 100644 zh/tutorials/1.0/microbit.md create mode 100644 zh/tutorials/1.0/modes.md create mode 100644 zh/tutorials/1.0/moving-on.md create mode 100644 zh/tutorials/1.0/pgzero.md create mode 100644 zh/tutorials/1.0/plotter.md create mode 100644 zh/tutorials/1.0/problems.md create mode 100644 zh/tutorials/1.0/python.md create mode 100644 zh/tutorials/1.0/repl.md create mode 100644 zh/tutorials/1.0/shortcuts.md create mode 100644 zh/tutorials/1.0/start.md create mode 100644 zh/tutorials/index.html diff --git a/Gemfile.lock b/Gemfile.lock index c5cc5df..ee6a5a5 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -4,15 +4,19 @@ GEM addressable (2.5.2) public_suffix (>= 2.0.2, < 4.0) colorator (1.1.0) + concurrent-ruby (1.1.3) em-websocket (0.5.1) eventmachine (>= 0.12.9) http_parser.rb (~> 0.6.0) - eventmachine (1.2.5) - ffi (1.9.23) + eventmachine (1.2.7) + eventmachine (1.2.7-x64-mingw32) + ffi (1.9.25) + ffi (1.9.25-x64-mingw32) forwardable-extended (2.6.0) http_parser.rb (0.6.0) - i18n (0.7.0) - jekyll (3.7.2) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.8.5) addressable (~> 2.4) colorator (~> 1.0) em-websocket (~> 0.5) @@ -27,32 +31,37 @@ GEM safe_yaml (~> 1.0) jekyll-redirect-from (0.14.0) jekyll (~> 3.3) - jekyll-sass-converter (1.3.0) - sass (~> 3.2) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) jekyll-sitemap (1.2.0) jekyll (~> 3.3) - jekyll-watch (2.0.0) + jekyll-watch (2.1.2) listen (~> 3.0) - kramdown (1.14.0) - liquid (4.0.0) + kramdown (1.17.0) + liquid (4.0.1) listen (3.1.5) rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) ruby_dep (~> 1.2) - mercenary (0.3.5) - pathutil (0.16.1) + mercenary (0.3.6) + pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (3.0.2) + public_suffix (3.0.3) rb-fsevent (0.10.3) rb-inotify (0.9.10) ffi (>= 0.5.0, < 2) - rouge (2.0.2) + rouge (3.3.0) ruby_dep (1.5.0) safe_yaml (1.0.4) - sass (3.4.23) + sass (3.7.2) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) PLATFORMS ruby + x64-mingw32 DEPENDENCIES jekyll (~> 3.1) @@ -60,4 +69,4 @@ DEPENDENCIES jekyll-sitemap BUNDLED WITH - 1.16.3 + 1.17.2 diff --git a/_includes/lang_list.html b/_includes/lang_list.html index 877da6c..e4b2095 100644 --- a/_includes/lang_list.html +++ b/_includes/lang_list.html @@ -1 +1,2 @@
  • English
    • +
  • 中文
    • diff --git a/_includes/nav_zh.html b/_includes/nav_zh.html new file mode 100644 index 0000000..3227656 --- /dev/null +++ b/_includes/nav_zh.html @@ -0,0 +1,31 @@ + diff --git a/_includes/themes/mu/zh.html b/_includes/themes/mu/zh.html new file mode 100644 index 0000000..c9beaab --- /dev/null +++ b/_includes/themes/mu/zh.html @@ -0,0 +1,70 @@ + + + + + + + + + {{ page.title }} + {% if page.description %}{% endif %} + + + + + + + + + + + + + + + + + + + + + + + + + {% if page.i18n %} + {% include nav_{{ page.i18n }}.html %} + {% else %} + {% include nav_en.html %} + {% endif %} +
    + {{ content }} +
    + + + + + + + + diff --git a/_layouts/zh.html b/_layouts/zh.html new file mode 100644 index 0000000..dc1045d --- /dev/null +++ b/_layouts/zh.html @@ -0,0 +1,6 @@ +--- +theme : + name : mu +--- +{% include JB/setup %} +{% include themes/mu/zh.html %} \ No newline at end of file diff --git a/zh/about.html b/zh/about.html new file mode 100644 index 0000000..3c7d85b --- /dev/null +++ b/zh/about.html @@ -0,0 +1,41 @@ +--- +layout: zh +title: 关于 Mu +i18n: zh +--- +

    关于 Mu

    +

    Mu是一个为初学者打造的Python代码编辑器。 +它的诞生离不开广大教师和学习者提供的反馈。

    + +
    + 下载 + 教程 + 操作指南 +
    +Mu's world + + +
    +
    +

    少即是多。

    +

    Mu 只有最必要的功能，所以用户不会受令人困惑的界面的干扰。

    +

    踏上最小阻力之路。

    +

    无论任务是什么，总有一种显而易见的方法可以用 Mu 做到。

    +
    + +
    +

    保持简单。

    +

    学习 Mu 既快速又简单~ 复杂阻碍了新手程序员迈出第一步。

    +

    玩得开心！

    +

    学习应该激发乐趣~ Mu帮助学习者快速创造并测试代码。

    +
    +
    + +Alan Kay +

    +图片来源 +

    + +

    引用来艾伦·凯 的 +访谈中 +关于学习编程的部分。描绘了Mu的愿景：Mu渴望成为“真实的东西”，成为初学者程序员在Python中迈出第一步的开发环境。

    diff --git a/zh/developers.html b/zh/developers.html new file mode 100644 index 0000000..15f4cc0 --- /dev/null +++ b/zh/developers.html @@ -0,0 +1,18 @@ +--- +layout: zh +title: Mu 开发 +i18n: zh +--- + +

    Mu 开发

    + +

    你愿意为 Mu 的发展做出贡献吗？ +(请不要认为这只是有经验的开发者的事情, 有很多方法可以为 Mu 做出贡献, 不论你的经验水平或技能水平如何)。

    + +

    我们的技术文档托管在很棒的 Read the Docs (http://mu.readthedocs.io/) 平台上。 +它不仅包含了为 Mu 做出代码贡献所需的详细信息, 而且还介绍了您可以做出贡献的许多其他方式 (包括对本网站进行更新)。 +最后, 它为我们的流程和对你可以为Mu做出的各种贡献的期望提供了指导。

    + +

    我们的源代码托管在 GitHub 上。

    + +

    如果有疑问，请直接在 讨论区中提问，有人会为你提出解答。

    diff --git a/zh/discuss.html b/zh/discuss.html new file mode 100644 index 0000000..cc28c9a --- /dev/null +++ b/zh/discuss.html @@ -0,0 +1,30 @@ +--- +layout: zh +title: Mu 讨论 +i18n: zh +--- + +

    Mu 讨论

    + +

    也许你有一个问题或者不确定如何用 Mu 做点什么？与其他Mu用户交流心得、分享知识和互相学习是非常好的做法。 +在一个好的环境中讨论这些事情是取得进步、结交朋友和取得成功的好方法。 +简而言之，Mu是一个以社区为重点的项目，我们创建了一个可以让大家聚集在一起的在线讨论社区。

    + +

    无论你的年龄、性别、宗教、种族或性取向如何，欢迎贡献，在这里不会有任何偏见。 +你可能会想：“这说的应该不是我”，但我们说的就是你！

    + +

    我们的主要讨论平台由一个名为 "Gitter" 的服务提供, 您可以通过点击下面的按钮或访问来注册并与社区联系: https://gitter.im/mu-editor/general

    +

    进入Gitter讨论版

    + + + + + diff --git a/zh/download.md b/zh/download.md new file mode 100644 index 0000000..d0d6f5b --- /dev/null +++ b/zh/download.md @@ -0,0 +1,91 @@ +--- +layout: zh +title: 下载 Mu +i18n: zh +--- + +# 下载 Mu + +安装Mu有很多种方法。 最简单的是下载适用于 Windows 或 macOS 的官方安装程序。 +如果你发现因为你正在使用的计算机被限制权限而无法安装 Mu 的话，你应该试试 PortaMu ，这是一种在 Windows 或 macOS 上从U盘运行 Mu 的办法。 +你也可以使用 Python 的内置`pip`工具来安装。 +一些 Linux 发行版已经有 Mu 的包了（你应该使用你的系统的包管理器来安装它）。 +最后，如果您使用的是 Raspbian（适用于 Raspberry Pi 的Linux 版本），则可以作为一个软件包来安装Mu。 + +如果你是一个专业的开发者，你可以在[GitHub](https://github.com/mu-editor/mu)上找到源代码。 + +
    +
    + Windows Logo +
    +
    +

    Windows 安装包

    +

    32位 + 64位 + 安装指南

    +
    +
    + +
    + +
    +
    + Apple Logo +
    +
    +

    macOS 安装包

    +

    下载 + 安装指南

    +
    +
    + +
    + +
    +
    + PortaMu Logo +
    +
    +

    PortaMu - 从U盘运行Mu

    +

    Windows 32位 + Windows 64位 + macOS + 安装指南

    +
    +
    + +
    + +
    +
    + Python Logo +
    +
    +

    Python 包

    +

    安装指南

    +
    +
    + +
    + +
    +
    + Raspberry Pi Logo +
    +
    +

    Raspbian

    +

    安装指南

    +
    +
    + +
    + +
    +

    Linux 用户请注意！

    +
    +

    在Linux上，为了使Mu能够与基于MicroPython的设备一起工作， + 您需要确保将自己添加到正确的权限组 + (通常是 dialout 或者 uucp 权限组). Also make + 同时也请确保您的系统会自动挂载这些设备，或者记得手动挂载。

    +
    +
    diff --git a/zh/help/1.0.html b/zh/help/1.0.html deleted file mode 100644 index 3a0c639..0000000 --- a/zh/help/1.0.html +++ /dev/null @@ -1,11 +0,0 @@ - - - - Redirecting… - - - - -

    Redirecting…

    - Click here if you are not redirected. - diff --git a/zh/help/1.0.md b/zh/help/1.0.md new file mode 100644 index 0000000..f1e8545 --- /dev/null +++ b/zh/help/1.0.md @@ -0,0 +1,58 @@ +--- +layout: default +title: Help for Mu 1.0.* +--- + +# Help for Mu 1.0 + +
    +
    +
    + + Tutorials + +
    +

    1. Tutorials

    +

    All the basics you need to know to get started and help with first + steps in using Mu. If you only read one thing, make it + this!

    +

    Go Level: SUPER EASY

    +
    +
    +
    +
    +
    + + Howto + +
    +

    2. How-to Guides

    +

    These deal with common tasks or problems in a simple + step-by-step manner. If you're looking for something specific, + look here.

    +

    Go Level: INTERMEDIATE

    +
    +
    +
    +
    +
    + + Chat + +
    +

    3. Discussion Channel

    +

    Our web-based chat-room is where you can ask questions or discuss + My with both other users and the developers of Mu.

    +

    Go Level: ADVANCED-ish

    +
    +
    +
    +
    + +**If you think you've found a bug in Mu, congratulations! Please [follow the steps outlined here](/en/howto/bugs).** diff --git a/zh/help/index.md b/zh/help/index.md new file mode 100644 index 0000000..2e0dfa1 --- /dev/null +++ b/zh/help/index.md @@ -0,0 +1,11 @@ +--- +layout: default +title: Available help. +--- + +# Available help + +Please see: + +* [Help for Mu 1.0](1.0). + diff --git a/zh/howto/bugs.md b/zh/howto/bugs.md new file mode 100644 index 0000000..7083f4f --- /dev/null +++ b/zh/howto/bugs.md @@ -0,0 +1,65 @@ +--- +layout: default +title: How to report a bug in Mu +i18n: en +--- +# How to report a bug in Mu + +
    + The first bug +
    +
    + +If you've ever written a line of code, you'll know that +[all software has bugs](https://www.history.navy.mil/our-collections/photography/numerical-list-of-images/nhhc-series/nh-series/NH-96000/NH-96566-KN.html). +This will be the case with Mu. + +If you think you have found a bug, simply click on the button below (you'll +need to have an account on GitHub) and then click the green "New Issue" button +found at the top right hand side of the page: + +
    +

    Report a Bug in Mu

    +
    + +When you create a new issue it will be given a number and the volunteer +developers, who write and maintain the code, will be informed by email. They +may annotate questions to your issue, if things are not clear. They may +immediately close it and mark it as "duplicate" (someone else has already +reported the bug -- and they'll reference the original issue). Sometimes +they'll close the bug and say "won't fix", because they disagree that it's a +bug *or* it's too trivial in order to invest any time. Finally, please be aware +of the famous [PEBCAK](https://en.wiktionary.org/wiki/PEBCAK) bug (Problem +Exists Between Chair and Keyboard). This simply indicates the user has caused +the problem (rather than the software): a misconfigured computer, a +misunderstanding, or perhaps a mismatch of expectation. ;-) + +There are generally two sorts of bugs: + +* Technical: the code has a mistake in it which causes the program to break. +* Behavioural: the code works correctly, but is doing the wrong thing. + +In both cases, for us to be able to fix the bug, we need **as much information +as possible**. When you create a new issue you should try to include, where +relevant, the following sorts of information: + +* What you were trying to do, +* What steps you took to make this happen, +* What you expected to happen, +* What actually happened, +* Why this difference is problematic (it may not be a bug!), +* Technical details like the version of Mu you're using, your OS version and + other aspects of the context in which Mu was running. + +Please remember to attach a [copy of the full log files for Mu](read_logs). + +Use plain and simple language to describe the problem and, if helpful, break +it down into steps so developers can easily recreate the issue. Please don't +assume we'll understand what you were trying to achieve -- honestly, it's best +if you try to imagine we (the developers) are a bunch of clever 5-year-olds. +Try to explain *everything* about the problem and don't assume we know what you +mean. We won't mind! ;-) + +If you would like to get more involved in the development of Mu, we'd love to +welcome you via the [Mu developer's website](http://mu.rtfd.io/). diff --git a/zh/howto/copy_files_microbit.md b/zh/howto/copy_files_microbit.md new file mode 100644 index 0000000..769e938 --- /dev/null +++ b/zh/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: + +
    + Files button +
    + +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)). + +
    + Moving files with a micro:bit +
    +
    + +
    +

    + WARNING: Don't toggle files off while the micro:bit is + busy!

    +

    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.

    +

    The solution is simply to press restart on the device while the "Files" + or "REPL" panes are off.

    +

    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).

    +
    +
    diff --git a/zh/howto/create_load_save.md b/zh/howto/create_load_save.md new file mode 100644 index 0000000..1f4b905 --- /dev/null +++ b/zh/howto/create_load_save.md @@ -0,0 +1,41 @@ +--- +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: + +
    + New, Load and Save buttons +
    +
    + +* **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. + +
    +

    Copy/Rename Files

    +
    +

    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.

    +
    +
    + +
    +

    Don't Use Python Module Names

    +
    +

    It's tempting to name your new file that uses the turtle + module as "turtle.py". Don't do this! If you name + your file after a module you're using in your code + then Python will break because it's trying to import + your code rather than the code from Python's standard + library!

    +
    +
    diff --git a/zh/howto/fix_code.md b/zh/howto/fix_code.md new file mode 100644 index 0000000..37a9484 --- /dev/null +++ b/zh/howto/fix_code.md @@ -0,0 +1,221 @@ +--- +layout: default +title: How to try to fix your own broken code +i18n: en +--- +# How to try to fix **your own** broken code + +

    DON'T PANIC!

    + +**THINGS WILL GO WRONG!** + +When starting to learn to code, it doesn't take long to realise that it's very +hard to write software that works. When software doesn't work, we say it has +a bug (see [how to report bugs in Mu](bugs) for the world's very first computer +bug). + +To be honest, professional software developers are just as capable of +writing buggy software as a beginner. The only difference is in the type of bug +they create. + +Beginner programmers make beginner mistakes like typing the wrong instructions, +setting out code in the wrong way (causing a syntax error) or simply asking +the computer to do something impossible. + +Professional programmers know the instructions that will work, understand how +to write their code correctly and appreciate the capabilities of a computer. +However, they often have blind spots, don't think through the full implications +of their code and can over-complicate the way they write software (thus making +it difficult to work out what's gone wrong). + +The very best programmers are humble enough to acknowledge their ignorance (and +are fearless to ask questions when something is unclear), pragmatic enough to +accommodate and compromise (if it leads to wider positive progress) and value +simplicity in style, structure and solution (it's extraordinarily hard to +solve problems with simplicity, and is the sign of a great programmer). + +With this in mind, there are certain thoughts, habits and processes you can +adopt to help you fix your inevitably broken code (everyone's code has bugs, +and those who claim otherwise are deluded). + +## It's Probably Your Fault + +Computers try very hard to carry out your instructions and it's very rare that +the computer will have a hardware bug. If your program doesn't work as you +expect it to, it's almost entirely going to be your fault since the computer +is only carrying out exactly what your instructions tell it to do. + +So, the most likely cause of the bug is that **you** have done something wrong +in your code. + +Upon reflection, this is a good thing, becuase more often than not, **you** can +also fix it by reading your code carefully, working out how what you wrote +isn't what you really meant to write, and then correcting things. + +## Don't Just Sit There, Do Something! + +The usual way you'll learn something has gone wrong is with an error message. +Unfortunately, to non-programmers error messages might as well look like this: + +
    + Silly error message +
    +
    + +As a beginner programmer these sorts of message may, at first, +appear intimidating and confusing. Remember, DON'T PANIC! Here's how to make +sense of such messages. + +There are different sorts of error and it's helpful to know which one you're +dealing with. Take a little bit of time to read the message. It could be a +*very long message* but you should start at the bottom. Such messages are +called stack traces and it'll look something like this: + +``` + File "/home/ntoll/mu_code/bad.py", line 1 + print("Hello) + ^ + SyntaxError: EOL while scanning string literal +``` + +In this instance we can see Python complaining about a `SyntaxError`, although +there are many different types of error (in technical parlance these are +called "exceptions"), four of which are listed below: + +* If you see a `SyntaxError` you've simply typed code in a way that Python + can't understand. Check you're not missing any special characters like `"` or + `:`. It's like putting. a full stop in the middle of a sentence. It's hard + for Python to understand exactly what you mean. + +* A `NameError` probably means you've typed something inaccurately. It's like + the difference between "Nicholas" and "Nicolas". They're two different people + but their names look very similar. Make sure you've typed your names + accurately! + +* A `TypeError` indicates you're trying to do impossible things with different + types of things. For example, how do you expect Python to handle + `"Hello" + 3`? In this case `"Hello"` is a string of characters and `3` is + a whole number. How do you add characters to numbers (and vice versa). I + don't know and you don't know, so how can we expect Python to know too? When + this happens Python will (legitimately) complain with a `TypeError`. + +* A `ValueError` happens when you try to do something with the right sort of + thing, but the with an unexpected value. For example, you may need to create + a data containing a year, month and date represented as whole numbers. + However, if you set the year as `-2018` you'll end up with a `ValueError` + (since years *are* whole numbers but may not be negative!). + +All the various exceptions (remember, that's what we call it when Python +indicates something has gone wrong) built into Python are +[documented on Python's website](https://docs.python.org/3/library/exceptions.html#concrete-exceptions). + +## Clearly Define the Problem + +So you may have found an exception at the end of the long stack trace. Instead +of putting your hand up, waiting for the teacher and then saying, "I have an +error", why not look up what the exception may mean (use the link above). +Alternatively, why not type "Python" followed by the name of the exception and +the message that comes with it into Google..? + +Welcome to programming, where most of your time is spent trying to make sense +of why stuff doesn't work as you expected. + +The most important aspect of this exercise is that you build up a picture of +what the program was doing, why it was doing it and how it got into a state +which caused it to fail. + +If the exception at the end of your stack trace doesn't help you work out the +answers to these questions then work backwards up the stack trace to learn what +steps Python took to get into the problematic end state. It's a bit like the +computer is presenting you with a list like this: + +* First I did this +* Then I did this +* Then I did this other thing +* After which I did this thing over here +* But then I couldn't do the thing you asked so, "ValueError" + +As mentioned, starting at the bottom tells you what caused the failure, but +you may need to read backwards to work out what led to the problem. + +## Check the Code (Checklist) + +Python is trying to be as helpful as possible by giving you **absolutely all +the information you may need** in order to fix the problem. This includes the +type of exception (so you know what the problem actually is), perhaps a helpful +message and then a filename and line number. + +These last two pieces of information tell you where, in your code, the problem +was encountered. In order to fix your code you should start where Python tells +you the problem was encountered. Once you're looking at the right line in the +right file you should develop a checklist of tests to make sure you've not +done something silly: + +* Is your indentation correct? (A common mistake.) +* Have you mixed up `=` and `==`? (I do this all the time.) +* Are you referring to the right thing? (Don't name things, `x`, `y` or `z` + and giving objects and variable meaningful names helps avoid this problem.) +* If you're calling a function, are you **sure** you understand what it's + doing? (If it returns a value, is the value what you were expecting? If not, + why not? Does your code work if the function encounters a problem?) +* Finally, don't just look at the line Python has given to you, explore the + lines that lead up to where the problem occured. (Context is important!) + +## Talk to the Rubber Duck + +If you're still struggling, talk to the rubber duck. + +
    + The PyCon UK Debug Duck +
    +
    + +[Rubber Duck debugging](https://en.wikipedia.org/wiki/Rubber_duck_debugging) is +a great technique for seeing things that may at first not seem obvious. It +simply involves explaining each line of code where the problem is found to +an imaginary programmer represented by a rubber duck (you don't have to use a +rubber duck, and it's probably best if you imagine yourself explaining things +to the duck rather than actually talk to a rubber duck... that would look +weird). + +This simple trick is a great way to shift your perspective to allow you to see +things you at first missed. For example, "First I set X to 15, then I loop over +the list X number of times so all the values are added to the total. Dammit. +The total is never reset to zero... no wonder it was so high. Why the hell +didn't I see that earlier..?" is a typical way this sort of thing plays out. + +## Ask for Help + +So you've looked up the exception, checked the code, rubber ducked for ten +minutes and the damn thing still won't work properly. Now what? + +Easy... just ask for help. + +Don't be afraid to ask questions - good developers are always asking questions. +Knowing how to ask and what the right questions are is an essential skill to +develop. Asking questions is NOT a sign you don't know what you're doing. To +good developers it's evidence that you're exploring the problem and a signal +that you're engaged and interested. + +So, learn to ask questions in the right sort of a way. + +"It doesn't work. What do I do?" is not going to be answered (at least in a +polite way). + +"I have a ValueError when I try to set the score in my game, but I don't know +why I keep getting negative numbers on line 123 of `my_game.py`" is much more +specific, sets a context and tells people *where* they can help. + +If all else fails, there's always this handy flow chart from the comic +[XKCD](https://www.xkcd.com/627/): + +
    + Flow chart of self help +
    +
    + +Debugging code can be frustrating, time consuming and disheartening. +However, once your program works, the elation you will feel is definitely worth +it. + +Best of luck! :-) diff --git a/zh/howto/index.html b/zh/howto/index.html new file mode 100644 index 0000000..9fd5090 --- /dev/null +++ b/zh/howto/index.html @@ -0,0 +1,37 @@ +--- +layout: zh +title: Mu 操作指南 +i18n: zh +--- + +

    Mu 操作指南

    + +

    这些简短的操作指南为您提供了简单的步骤来实现一个明确的目标。

    + +

    关于安装 Mu

    + + + +

    关于使用 Mu

    + + + +

    解决问题

    + + diff --git a/zh/howto/install_macos.md b/zh/howto/install_macos.md new file mode 100644 index 0000000..fcc77db --- /dev/null +++ b/zh/howto/install_macos.md @@ -0,0 +1,76 @@ +--- +layout: default +title: How to install Mu on macOS with the Official Installer +i18n: en +--- + +# How to install Mu on macOS with the Official Installer + +Installing Mu on macOS is super easy. + +Mu will run on any machine running macOS version 10.11 El Capitan or later. There is [advice on Apple's website](https://support.apple.com/en-us/HT201260) on how to check your macOS version. + +## Step 1 - Download Mu Installer + ++ [Download](/en/download) the installer for macOS. + +## Step 2 - Open the Installer + ++ Open your Downloads folder - click "Go", then "Downloads" on the Finder menu. + +
    + Mac OS open downloads +
    +
    + ++ Double click the Mu installer disk image (a .dmg file). + +
    + Mac OS downloads +
    +
    + +When you open the installer you'll be asked to accept the software license +agreement and then your computer will verify the package is not corrupted (this +may take a couple of minutes). + +## Step 3 - Install Mu + ++ Click, hold and drag the "Mu" icon into the "Applications" folder. + +
    + Mac OSX installer step 1 +
    +
    + +## Step 4 - Installing + +Mu will install into the Applications folder on your Mac. + +
    + Mac OSX installer step 2 +
    + +## Step 5 - Start Mu + ++ Open your Applications folder - click "Go", "Applications" on the Finder menu. + +
    + Mac OS open downloads +
    +
    + +Double-click on the Mu icon. You'll see a dialog to check you want to open +Mu. Click "Open": + +
    + Click to Open
    +
    + +**This can take some time as OSX checks the Mu package, but you'll only ever have to do it once.** + ++ Next time you launch Mu you will be able to just double click the Mu icon. + +
    + Mac OSX installer step 3 +
    diff --git a/zh/howto/install_raspberry_pi.md b/zh/howto/install_raspberry_pi.md new file mode 100644 index 0000000..8637956 --- /dev/null +++ b/zh/howto/install_raspberry_pi.md @@ -0,0 +1,67 @@ +--- +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 can use the **Recommended Software** application to install **mu**. + +## Step 1 - Update your Raspberry Pi + ++ Open a terminal by selecting Accessories and Terminal from the menu + +
    + pi open terminal +
    +
    + ++ Enter the following commands to update Raspbian + +```bash +sudo apt-get update +sudo apt-get dist-upgrade +``` + +## Step 2 - Install Mu + ++ Open the Recommended Software application from the Preferences menu. + +
    + pi open recommended software +
    +
    + ++ Select Mu from the list of applications to install. + +
    + select mu +
    +
    + ++ Click OK to start the installation process. + +
    + click ok +
    +
    + +## Step 3 - Start Mu + ++ Open Mu by selecting it from the Programming menu. + +
    + pi open mu +
    +
    + +
    +

    Install from the command line

    +
    +

    You can also install Mu from the command line using the command:

    +

    sudo apt-get install mu-editor

    +
    +
    diff --git a/zh/howto/install_windows.md b/zh/howto/install_windows.md new file mode 100644 index 0000000..f7f92b1 --- /dev/null +++ b/zh/howto/install_windows.md @@ -0,0 +1,191 @@ +--- +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 + +Installing Mu in Windows is super easy (if you are a network administrator we +recommend you [read the instructions at the bottom of the page](#admins)). + +
    + mu windows installer +
    +
    + +Mu works on Window 7, 8 and 10 in 32 bit and 64 bit. It's a good idea to make sure your system to up-to-date with all Windows updates. + +If you are in an educational setting you may need to get your system administrator to run the installer for you. + +## Step 1 - Download Mu Installer + +[Download](/en/download) the correct 32 bit or 64 bit installer for your operating system. + +To find out whether you need a 32 bit or 64 bit installer: + ++ Opening Explorer, right click "This PC" and select properties. + +
    + open pc properties +
    +
    + ++ The operating system type will be shown under System, System Type. + +
    + system type +
    +
    + +There is also [advice on Microsoft's website](https://support.microsoft.com/en-us/help/15056/windows-7-32-64-bit-faq) for finding whether you are using 32 or 64 bit Windows. + +# Step 2 - Run the installer + ++ Find the installer you just downloaded (it's probably in your Downloads folder) + +
    + Windows 7 - Find the installer +
    +
    + +
    + Windows 10 -Find the installer +
    +
    + ++ Double-click the installer to run it. + + + +## Step 3 - Start the install + +Confirm the version of Mu you'll be installing and click "Next". + +
    + Windows installer step 1 +
    +
    + +The version number will likely be different from the one shown. + +## Step 4 - License Agreement + +Review the license and click "Agree". + +
    + Windows installer step 2 +
    +
    + +## Step 5 - Choose Users + +Select if you want to install Mu for all users, or just yourself and click "Next". + +Please note, if your user account does not have administrative rights this step might not appear on your installation process. +If it does, the installer might only work if you select the "Install just for me" option. + +
    + Windows installer step 3 +
    +
    + +## Step 6 - Choose Install Location + +Select the installation destination (you can usually leave this as the default) and click "Install". + +
    + Windows installer step 4 +
    +
    + +## Step 7 - Installing + +Go make a cup of coffee as Mu installs on your computer. + +
    + Windows installer step 5 +
    +
    + +## Step 8 - Complete + +The installation has completed successfully, click "Finish" to close the installer. + +
    + Windows installer step 6 +
    +
    + +## Step 9 - Start Mu + +You can start Mu by clicking on the icon in the Start menu. + +
    + Windows start mu +
    +
    + +
    +

    ATTENTION NETWORK ADMINISTRATORS

    +
    +

    If you are a network administrator who needs to install Mu on + many machines we'd like to answer a couple of common queries and provide + some technical context and information:

    + +
    +
    Why is the installer a .exe rather than an MSI?
    +
    In 2015 Microsoft announced that, while MSI won't go away any time + soon, they want developers to move onto other, more modern, packaging + solutions. We use a simple and easy to use + packaging + system which allows us to automatically and reliably create + installers with zero manual intervention.
    +
    Why is the default install per-user rather than system wide?
    +
    Engineers at Microsoft have + advised + us that per-user is the preferred for the following reasons: +
      +
    • Non-admin users can use the installer.
      • +
    • Such installations keep users isolated from each other.
      • +
    • Per-user installation means security and reliability + problems encountered by running as admin are avoided.
      • +
    + For more information about installation contexts, please see + this article on Microsoft's website. +
    + +
    +

    We understand that, as a system administrator, you know what + you're doing and simply want to install Mu, system wide, on all the + machines under your control. In this case, you need + to run the installer with the following flags: + mu-editor_win64.exe /S /AllUsers

    + +

    The /S flag tells the installer to work in "silent" mode + (i.e. you won't see the windows shown in the screenshots above) and the + /AllUsers flag makes Mu available to all users of the system + (i.e. it's installed "system wide").

    +

    If you encounter problems or wish to give feedback, please + get in touch.

    +
    +
    diff --git a/zh/howto/install_with_python.md b/zh/howto/install_with_python.md new file mode 100644 index 0000000..2b6114c --- /dev/null +++ b/zh/howto/install_with_python.md @@ -0,0 +1,97 @@ +--- +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 it is easy to install Mu with Python's +built-in package manager, [`pip`](https://pip.pypa.io/en/stable/installing/). +**Please note: this method does not currently work on Raspberry Pi** (use +[these instructions instead](/en/howto/install_raspberry_pi)). +If you're on Windows and would rather not type commands you should use the +[Windows installer for Mu](install_windows) instead. If you're using OSX on a +Mac and want to use the simple drag-and-drop installer instead, you should use +the [OSX installer for Mu](install_macos). + +We recommend you run the following commands in a +[virtualenv](https://pypi.org/project/virtualenv/) +or other means of isolating your Python environment. + +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. + +
    +
    Warning
    +

    Depending on how your machine + is set up, you may encounter errors. The most common are:

    +
      +
    • You don't have permission to use pip 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).
      • +
    • You're using the wrong or and old version of pip. If + you have Python 2 installed on your machine, you must + make sure you're using pip3. If pip complains + it is out of date, follow these + instructions for + updating pip.
      • +
    • You can't even run pip, 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).
      • +
    +

    If you're still facing problems, perhaps try using another installation + method (HINT: if you're on Windows or using OSX on a Mac, use the installer + for the appropriate platform instead). + As a last resort why not see if anyone can help you in the + discussions.

    +
    +
    + +## 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 if you've not isolated Mu in a virtualenv. + +Simply use `pip` to install `shortcut` and then use `shortcut` on Mu: + +``` +pip3 install shortcut +shortcut mu-editor +``` diff --git a/zh/howto/microbit_settings.md b/zh/howto/microbit_settings.md new file mode 100644 index 0000000..db48e43 --- /dev/null +++ b/zh/howto/microbit_settings.md @@ -0,0 +1,50 @@ +--- +layout: default +title: How to minify your MicroPython scripts and use a custom runtime on the BBC micro:bit +i18n: en +--- +# How to minify your MicroPython scripts and use a custom runtime on the BBC micro:bit + +Being small is one of the strengths of the BBC micro:bit. However, small +also applies to the amount of storage space on the device which can be +problematic if you have MicroPython scripts that are simply too long to fit +onto the micro:bit. + +Happily, there is a way to "minify" (remove the comments and compress the +white-space in your source code) so that the program remains unchanged but the +source code takes up less room. + +Sometimes, if you're an advanced user, you want to try out a version of the +MicroPython runtime for the micro:bit that's different to the one already +included in Mu. + +Happily there's a way to tell Mu which runtime `.hex` file to use instead of +the default. + +Such settings for the micro:bit are found in the "Mu Administration" dialog +which you can see by clicking on the "cog" icon in the bottom right hand +corner of Mu's window (highlighted in red in the image below). + +
    + The cog button +
    +
    + +As shown below, select the "BBC micro:bit Settings" tab and toggle the "minify" +checkbox to switch minification on or off. Use the text box to enter the *full +path* to the custom MicroPython runtime. + +
    + BBC micro:bit settings +
    +
    + +
    +

    Attention! Ensure the runtime exists!

    +

    Mu will complain if the file path to the custom + MicroPython runtime doesn't exist. In this instance the default runtime + will be used.

    +

    These settings will remain in place when you re-start Mu. If you wish to + revert back to the default runtime, simply delete the path.

    +
    +
    diff --git a/zh/howto/pgzero_sounds_images.md b/zh/howto/pgzero_sounds_images.md new file mode 100644 index 0000000..7e2fbde --- /dev/null +++ b/zh/howto/pgzero_sounds_images.md @@ -0,0 +1,35 @@ +--- +layout: default +title: How to add new images, fonts, sounds and music to Pygame Zero +i18n: en +--- +# How to add new images, fonts, sounds and music to Pygame Zero + +PyGame Zero makes it very easy to create simple graphical games with Python. +Such games need images to display on the screen, fonts for writing text, sounds +to play when certain things happen or music to set the mood of the game. + +Mu makes it very easy to add such game "assets" when in PyGame Zero mode ~ four +buttons labelled "Images", "Fonts", "Sounds" and "Music": + +
    + Images and Sounds buttons +
    +
    + +Clicking on each button will open up your computer's file manager in the +correct directory. All you need to do is drag and copy assets into the +directory so PyGame Zero can find them. Remember only copy images into the +directory opened by the "Images" button, fonts into the directory opened by the +"Fonts" button, sound files into the directory opened by the "Sounds" button +and music into the directory +opened by the "Music" button. Once the files are copied into the right place +you'll be able to use them in your game, +[as explained in the PyGame Zero documentation](https://pygame-zero.readthedocs.io/en/stable/introduction.html#sounds-and-images). + +This process for the "Images" button is shown below: + +
    + Add an image to PyGame Zero +
    +
    diff --git a/zh/howto/python3_envars.md b/zh/howto/python3_envars.md new file mode 100644 index 0000000..2ba6832 --- /dev/null +++ b/zh/howto/python3_envars.md @@ -0,0 +1,53 @@ +--- +layout: default +title: How to use environment variables to configure GPIOZero in Python3 Mode. +i18n: en +--- +# How to use Environment Variables to Configure GPIOZero in Python3 Mode + +Some libraries (such as GPIOZero) look up configuration information in +user-defined settings called environment variables. Mu allows you to define +what these environment variables should be so that whenever you run a script +or use the REPL in Python 3 mode, these settings are available to your code. + +If you look at the [documentation for the GPIOZero library](https://gpiozero.readthedocs.io/en/stable/remote_gpio.html#environment-variables), +you'll see that you probably need to set the following environment variables +for it to work properly: + +``` +GPIOZERO_PIN_FACTORY=pigpio +PIGPIO_ADDR=192.168.1.3 +``` + +The steps to make this happen in Mu are very simple: + +Click on the "cog" icon in the bottom right hand corner of Mu's window +(highlighted in red in the image below). This will open up the +"Mu Administration" dialog. + +
    + The cog button +
    +
    + +Select the "Python 3 Environment" tab and fill in the environment variables +as shown below. Each environment variable must be on its own line and of the +form NAME=VALUE. + +
    + Environment variables +
    +
    + +
    +

    Attention! The settings shown above are examples

    +

    The correct value of the PGPIO_ADDR + environment variable for your system will be different from the example + shown above (highlighted in blue). Please consult the + documentation for GPIOZero + for more information.

    +

    Environment variables are saved and will remain in place when you + re-start Mu. If you want to delete an environment variable, simply remove + it from the text area shown above!

    +
    +
    diff --git a/zh/howto/read_logs.md b/zh/howto/read_logs.md new file mode 100644 index 0000000..90605d5 --- /dev/null +++ b/zh/howto/read_logs.md @@ -0,0 +1,93 @@ +--- +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. + +Mu keeps up to 5 days worth of logs in a special 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 (highlighted +in red below): + +
    + The cog button +
    +
    + +The "Mu Administration" window will open with the "Current Log" tab selected +(this is the one you need). It should look something like this: + +
    + The log window +
    +
    + +Mu **appends** lines to the log file, so the most recent line is at the end of +the logs. + +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). + +
    +

    Copying the Log is Easy

    +
    +

    Copying the contents of the log file takes just three steps:

    +
      +
    1. Click on the content of the log file to bring it into focus, + then either drag your mouse to highlight specific lines, or press + CTRL-A (CMD-A on a Mac) to "select all".
      2. +
    2. Press CTRL-C (CMD-C on a Mac) to "copy" the contents of the + log file into your clipboard.
      3. +
    3. Click to move focus onto a web form or other target for the + contents of the log and press CTRL-V (CMD-V on a Mac) to + "paste" the contents of the log from your clipboard into the + desired location.
      4. +
    +
    +
    + +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. +It looks 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 of dashes: `-----------------`. 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. diff --git a/zh/howto/think_code.md b/zh/howto/think_code.md new file mode 100644 index 0000000..3d2e077 --- /dev/null +++ b/zh/howto/think_code.md @@ -0,0 +1,35 @@ +--- +layout: default +title: How to think your way around a problem in code +i18n: en +--- +# How to think your way around a problem in code + +You learn to code in order to make stuff that you find important. Often this is +called "scratching your itch" (where the itch is your particular passion). +Perhaps you have a great idea for a goofy game, maybe you've thought of a +way to improve people's lives through helpful technology or you may just want +to program a computer to do something just for you. + +No matter what, you're going to have to turn your raw idea into something that +works. Here's the good news: so long as you don't need to break the laws of +nature, given enough time and effort, anything is possible. The bad news is +that while something may be possible, it doesn't mean that it's easy or even +worth the effort. Furthermore, you may not have the time or resources required +to make the thing that you want, nor even realise how much time or effort +is needed. + +How do you make a start? How do you make sure you're doing the right thing? +How do you know when you're done? + +There are no right answers to these questions because each project is +different and the people involved are all different. However, the following +advice may help you learn the answers for your project with your collaborators. + +## What's the Problem? + +## Who's the User? + +## Why your Solution? + +## Has this been done Before? diff --git a/zh/howto/use_portamu.md b/zh/howto/use_portamu.md new file mode 100644 index 0000000..48d23bc --- /dev/null +++ b/zh/howto/use_portamu.md @@ -0,0 +1,103 @@ +--- +layout: default +title: How to Use PortaMu to run Mu Anywhere +i18n: en +--- + +# How to use PortaMu to run Mu anywhere + +
    + PortaMu Logo +
    +
    + +Sometimes it's not possible to install Mu because the computers you have +available are locked down by somebody else. + +Perhaps you find yourself running a workshop in a library or your school's +network administrator is more likely to say "get off my lawn" than "let me help +you with that". + +Don't worry, thanks to the remarkable work of 14 year old +[Josh Lowe](http://allaboutcode.co.uk/), you can run Mu from a pendrive +(those dongle-thingamabobs for storing files that you plug into the computer's +USB port). + +This technique should work on both Windows and OSX. + + + +## Windows + +[Download](/en/download) the correct 32 bit or 64 bit version of PortaMu for +your operating system. + +To find out whether you need a 32 bit or 64 bit installer: + ++ Opening Explorer, right click "This PC" and select properties. + +
    + open pc properties +
    +
    + ++ The operating system type will be shown under System, System Type. + +
    + system type +
    +
    + +There is also [advice on Microsoft's website](https://support.microsoft.com/en-us/help/15056/windows-7-32-64-bit-faq) for finding whether you are using 32 or 64 bit Windows. + +Once you've downloaded the correct zip file, extract it (right click, then +select extract) onto the already attached pendrive. When you plug the pendrive +into a locked-down computer, navigate to the folder on the pendrive where you +extracted Mu and double click on the `Launch Mu.bat` file to start. **It may +take some time for Mu to launch** because of the relative slowness of +pendrives. + +Sometimes, depending upon the machine you're using, Windows may say that it is +protecting your PC from an unrecognised application. + +
    + Windows protector +
    +
    + +The solution is to click on the "More info" link: + +
    + Windows protector +
    +
    + +Then click on the "Run anyway" button. + +
    + Windows protector +
    +
    + +## Mac OSX + +You simply need to [download](/en/download) the existing OSX installer, copy it +onto the pen drive and double click it on the pendrive. However, instead of +copying the `mu-editor` icon to the "Applications" folder, you should simply +double click it and Mu should launch. As mentioned before, this may take some +time and, when run for the first time, OSX may ask you to confirm you want to +run it. + +That's it! diff --git a/zh/index.html b/zh/index.html new file mode 100644 index 0000000..671a37b --- /dev/null +++ b/zh/index.html @@ -0,0 +1,21 @@ +--- +layout: zh +title: Mu 编辑器 - Code With Mu +i18n: zh +--- + +
    +

    Code With Mu： + 一个适合初学者的 Python 编辑器。 +

    +
    +
    +

    + 下载 + 从这里开始 +

    +
    + +
    + 你好 Mu +
    diff --git a/zh/thanks.html b/zh/thanks.html new file mode 100644 index 0000000..397628f --- /dev/null +++ b/zh/thanks.html @@ -0,0 +1,400 @@ +--- +layout: zh +title: Mu 感谢 +i18n: zh +--- + +

    感谢

    + +

    如果没有那些志愿开发者们投入自己时间和精力来改善 Mu 、给予帮助和支持，就不会有 Mu。 +尽管如此，认可其他可能不是开发人员但同样为 Mu 做出重大或必要贡献的人及他们的帮助和工作也是很重要的。 +如果您发现 Mu 很赞，为什么不感谢一下以下人员和组织？ 只需要一分钟的时间来发表您的赞赏。

    + +
    +
    + + Carrie Anne + +
    +
    +

    Carrie Anne Philbin

    +

    Carrie Anne is the director of education at the + Raspberry Pi Foundation. + She gave a keynote + address to the EuroPython 2015 conference in Bilbao + where she set the assembled delegates some homework (once a teacher, always + a teacher). She asked that we make a Python editor tailored to the needs + of beginner programmers and based on the feedback she had received from + the many teachers who had used a Raspberry Pi to teach Python. Many of the + design decisions taken when making Mu are directly influenced by Carrie + Anne's invaluable work and feedback. Thank you Carrie Anne, we hope Mu gets + a good grade as our homework submission. :-)

    +
    +
    +
    +
    + + Dan Pope + +
    +
    +

    Dan Pope

    +

    Dan Pope heard Carrie Anne's keynote address at EuroPython. Both he and + I (Nicholas) took up the challenge to create a beginner-friendly editor, + and while at the conference started to code up a + very simple editor + called Puppy. Work stalled until, as a contribution to the BBC's + micro:bit project, a native MicroPython + editor was needed. The core of Puppy became the first steps to Mu. Thanks + Dan for helping to make those first steps.

    +

    Dan needs further thanks because he is also the creator and maintainer + of Pygame Zero, + a Python library that makes it easy for beginner programmers to create + games with Pygame. It forms the basis of Mu's Pygame Zero mode.

    +
    +
    +
    +
    + + Damien George + +
    +
    +

    Damien George

    +

    Damien created and is the maintainer of the amaazing + MicroPython project, a version of the + Python programming langauge for microcontroller based devices. Damien was + instrumental in the success of MicroPython on the BBC micro:bit device and + Adafruit's CircuitPython is based upon MicroPython.

    +

    Mu was originally created as an editor for MicroPython on the BBC + micro:bit and Damien contributed code to that made the REPL on + an attached device available via Mu.

    +

    Thanks Damien for your extraordinary work on MicroPython and your help + with the early versions of Mu's REPL.

    +
    +
    +
    +
    + + Carlos Pereira Atencio + +
    +
    +

    Carlos Pereira Atencio

    +

    Carlos has made significant contributions to Mu in several ways. First, + he created and has maintained the automation involved in making versions of + Mu available for download. Second, he has been invaluable in "housekeeping" + efforts involved in the project: triaging bugs, closing outstanding issues, + reviewing code and generally making the Mu development community a positive + and friendly place. Finally, he has + contributed + huge numbers of bug fixes, features and re-factored code to Mu and the + projects upon which it depends. Thank you Carlos for running with those + tasks that are often overlooked or left unacknowledged. Mu wouldn't be + the friendly project it is, without all your help.

    +
    +
    +
    +
    + + Zander Brown + +
    +
    +

    Zander Brown

    +

    Zander, like Top Gear's + the Stig, is a bit of + a mystery. Nobody has ever met him in real life, and all interactions with + Zander are via copious GitHub comments, pull requests and bug fixes. Some + say he's an alien being from another dimension, others claim him to be + a rogue artificial intellegince running rampant in random Git repositories, + yet more people whisper in hushed tones that he's merely a pseudonym for + Bill Gates, coming out of retirement to contribute to free software + projects. All I can say is that I'm thankful for his considerable + conributions to Mu's code base, eagle-eyed code reviews and seemingly + limitless Pythonic knowledge.

    +
    +
    +
    +
    + + Tim Golden + +
    +
    +

    Tim Golden

    +

    Tim is one of those rare legendary beasts of the coding world: a tame + Python core developer. He specialises in Python on Windows and he has + brought this invaluable knowledge to the development of Mu on many + occasions. Since Mu is developed mainly on Linux, if Mu works well on + Windows, it's probably because of Tim's intervention. Tim also makes + considerable contributions to Python in education in the UK by helping to + run workshops for kids and taking an active part in engaging with teaching + colleagues. Again, Tim's considerable experience and knowledge resulting + from such work is regularly brought to the development of Mu. Thank you + Tim for all your hard work.

    +
    +
    +
    +
    + + Ann McMeekin Carrier + +
    +
    +

    Ann McMeekin Carrier

    +

    Ann is an exceptionally + talented + "User + eXperience" (UX) researcher. Her passion for collaboratively + putting users at the centre of an evidence based development process is + both inspiring and the antidote to the naive "just build this list of + features" approach to software project management.

    + +

    Ann's connection with Mu is advisorial in nature. She supported, advised + and provided pointers at a crucial time in Mu's development. If the user + interface feels simple and easy to use it's because Ann pointed the way to + the approach to take for arriving at the interface. Another, more concrete + example of Ann's contribution can be found in her written Q&A + responses that frame Mu's + developer documentation about UX. + Thank you Ann for your help, support and humour. Thank you for ensuring + beginner programmers remain at the centre of Mu's development. Thank you + for your wisdom and professionalism.

    +
    +
    +
    +
    + + Steve Hawkes + +
    +
    +

    Steve Hawkes

    +

    Steve is a legend in the UK's Python community. Not only is he a coder + who runs an amazing digital agency that + specialises in working with the not-for-profit sector, but he's an + exceptionally talented designer. The Mu logo (Pynelope the Python), + aspects of Mu's user interface (the big round buttons) and the Pirate flag + used on our 404 page are all his + creations. Steve is especially generous with his time when creating such + resources for use and re-use by the wider Python community. Thank you Steve + for your contributions to Mu and thank you for your tireless work to make + the Python community look good on print, screen and other media.

    +
    +
    +
    +
    + + Ben Mustill-Rose + +
    +
    +

    Ben Mustill-Rose

    +

    Ben is a developer at the BBC where he tests their digital on-demand + platform, iPlayer. He has a + great talent and passion for making software more accessible, especially + for those with vision impairment or loss. He also spends a large part of + his free time organising and running events to help kids learn to code. Ben + has ensured that the text widget used by Mu (QScintilla) + has all the features needed to make it integrate with a computer's + accessibility features (for example, a screen reader). Learning to code + should be accessible for everybody, no matter the physical challenges they + may face. Thank you Ben for your inspiring work, determination and patience + when it comes to making our software available to all.

    +
    +
    +
    +
    + + Thomas Kluyver + +
    +
    +

    Thomas Kluyver

    +

    Thomas should be thanked for two aspects of Mu. The REPL in Python3 mode + is based on his + qconsole widget + that makes it easy to integrate the amazing + Jupyter Project into Qt based apps like + Mu. It was ridiculously easy to integrate into Mu and the powerful features + it brings (reproducible computational narratives, embedded plots, automatic + help, and other iPython related goodies) is a taste of things to come when + students graduate to "proper" Jupyter notebooks. Thomas's other + contribution is the Windows based installer built with his super-cool + Pynsist tool for + creating Windows installers for Python applications. I found a couple of + bugs and had a few requests, and Thomas was very gracious to accept my + suggested changes. The result is the super easy installer we have for + Windows. Thank you Thomas! You rock!

    +
    +
    +
    +
    + + Rene Dudfield + +
    +
    +

    René Dudfield

    +

    René is the maintainer of the insanely wonderful + Pygame library for programming + games with Python. He does an amazing job, as a volunteer, packaging, + testing, fixing and generally keeping the development moving forward on + what is an extraordinarily powerful and non-trivial project. Pygame is, + of course, what sits behind Dan's Pygame Zero and this relationship + encapsulates the Mu philosophy: you start with a simple tool (like Mu or + Pygame Zero) which forms a bridge to "real" Python programming (be that + a professional code editor or the Pygame library). It is only by sitting + on the shoulders of giants like René that we can build such + beginner friendly tools. Finally, René's sense of playful fun, + celebration of off the wall excentricity and general merry mischief + contributes to making Python such a wonderful community. Keep it up + René, and thank you!

    +
    +
    +
    +
    + + Kushal Das + +
    +
    +

    Kushal Das

    +

    Kushal is, quite simply, an inspiring figure in the Python community. + His passion for facilitating education and learning is infectious and + breathtaking: boundless enthusiasm and effort result in extraordinarily + successful online and offline workshops for beginner programmers in his + native India and beyond. So I was especially proud that Kushal found + some of his precious time to help package Mu for + Fedora based Linux distributions. In + this respect he was a path-finder since it was the first time Mu had been + properly packaged. Kushal has also provided lots of moral support during + the development of Mu, and I hope he finds a way to help me with a Hindi + translation. Thank you Kushal!

    +
    +
    +
    +
    + + Martin O'Hanlon + +
    +
    +

    Martin O'Hanlon

    +

    I first met Martin at PyCon UK where he single handedly presented a + tutorial about Python and Minecraft to a room full of enraptured young + coders. To say that Martin has a gift for teaching is an understatement. + His work and enthusiasm for empowering young people in the digital realm + is inspiring and a joy to behold. Martin's contributions to Mu relate to + his patient, comprehensive and incredibly useful testing of Mu on the + various target platforms. He has also been a sympathetic and pro-active + bridge between Mu development and the Raspberry Pi education team. His + willingness to facilitate invaluable and crucial meetings between + developers and educators was a fundamental aspect of Mu's improvement in + the later stages of its development. Thank you Martin, especially for your + patience with all those bugs! :-)

    +
    +
    +
    +
    + + Raspberry Pi + +
    +
    +

    Raspberry Pi

    +

    The Raspberry Pi is perhaps the + most successful computing-in-education project in history. With over + 20 million units shipped and a plethora of online content for beginner + programmers, this plucky small computer is transforming computing education + from an uninspiring exploration of office and productivity software into + an exercise in digital empowerment.

    + +

    I felt very honoured when + Carrie Anne got in touch to say that the Raspberry Pi Foundation were + interested in supporting my work on Mu. The result has been a significant + re-write and the addition of plenty of cool new features based upon the + feedback of friends in the Raspberry Pi Foundation's education team and + direct observation of beginner coders at several of Raspberry Pi's many + Code Clubs here in the UK. Most importantly, Raspberry Pi should be + congratulated and celebrated for putting their money where their mouth is: + by supporting free software developers like myself, they are supporting the + ecosystem and work of those upon whom they depend. Thank you for your + support! I hope Mu helps you with your mission to change the world of + computing education for the better.

    +
    +
    +
    +
    + + Adafruit + +
    +
    +

    Adafruit

    +

    Adafruit, the brainchild of + Limor "ladyada" Fried, makes the coolest, most playful and fun boards on + the planet. Importantly, they are hugely influential in the open source + hardware community and support efforts in this domain (for example, they + actively develop and support CircuitPython, a version of MicroPython + customized for their boards). The free and beautifully designed + Adafruit Learning System is a + veritable box of delights for beginner programmers.

    + +

    With respect to Mu, + Adafruit have contributed code, bug fixes and suggestions for new features. + Also, if you use the plotter, you're using code that originated with + Adafruit. Thank you for your inspiring work, contributions to Mu and for + making CircuitPython such fun to use on such a wide variety of devices.

    +
    +
    +
    +
    + + BeeWare + +
    +
    +

    BeeWare

    +

    BeeWare is an amazing open source + project that makes it possible to create Python applications with rich + graphical user interfaces that run on many different platforms (iOS, + Android, Windows, MacOS, Linux, Web, and tvOS).

    + +

    BeeWare is connected with Mu in a couple of ways. The visual debugger in + Mu is inspired by and takes a similar approach to the BeeWare debugger + called + BugJar. When + packaging Mu for Mac OSX we use BeeWare's amazing + Briefcase + project. You cannot underestimate how hard it is to package Python + applications on Mac OSX, and without the initial help of PyBee's founder, + Russell Keith-Magee and + subsequent use of Briefcase we'd still be scratching our heads and + wondering how to make Mu easily installable on Mac OSX.

    +
    +
    +
    +
    + + Micro:bit + +
    +
    +

    Micro:bit Educational Foundation

    +

    The BBC micro:bit is why Mu + exists: Mu was created in response to feedback from teachers who found + the limitations of a browser based editor problematic. It was created under + the auspices of the Python Software + Foundation as a volunteer led contribution to the project.

    +

    While Mu has never had any formal recognition by the Micro:bit project, + the associated educational foundation funded work on updating the way Mu + flashes MicroPython onto the device. + The new method of flashing is almost instantaneous (to the extent that we + had bug reports saying it didn't work, when in fact it worked so quickly + folks missed it!).

    +

    Thank you to the Micro:bit Educational Foundation for their support and + for being the original inspiration that led to Mu!

    +
    +
    diff --git a/zh/tutorials/1.0/adafruit.md b/zh/tutorials/1.0/adafruit.md new file mode 100644 index 0000000..3d76255 --- /dev/null +++ b/zh/tutorials/1.0/adafruit.md @@ -0,0 +1,60 @@ +--- +layout: default +title: Adafruit Boards and Mu +i18n: en +--- + +# Adafruit Boards and Mu + +[Adafruit](http://adafruit.com/) make a wide variety of amazing microcontroller +based boards which are capable of running their own version of MicroPython +called [CircuitPython](https://www.adafruit.com/circuitpython). These boards +range from the incredibly small to powerful boards with tons of built-in +hardware features. Even better, Adafruit have nurtured and grown a thriving +online community associated with CircuitPython and their amazing line of +boards. This is a supportive and helpful place to be if you're a beginner +coder -- especially if you're into making small embedded computers (such as the +boards made by Adafruit) do funky stuff with real-world peripherals, then this +is the place for you. + +Mu's Adafruit mode is made in collaboration with Adafruit and makes it very +easy to create projects and write code for their line of boards. For example, +your Python code to run on Adafruit boards is *stored on the boards*. Mu +understands this and will detect and open files on any device plugged into your +regular computer. + +The extra functionality provided by Adafruit mode is contained in the following +buttons: + +
    + Buttons from the Adafruit mode +
    +
    + +The "Serial" button opens a serial data connection to the Adafruit board you +may have connected to your computer. This will result in a new pane between the +text editor and Mu's footer. Any serial data emitted from the device will +appear here. If you need to drop into the CircuitPython REPL you should make +sure the pane has keyboard focus (just click it!) and then type CTRL-C, as +shown below: + +
    + Adafruit serial +
    +
    + +The "Plotter" button opens Mu's plotter. If your device is outputting tuples +of numbers via the serial connection, the plotter will display them as a +graph. This is incredibly useful for visualising any data you might be +measuring via the device. For more information read the +[tutorial about Mu's plotter](plotter). + +
    + Adafruit plotter +
    +
    + +If you're looking for things to do with your Adafruit board, there's no better +place to look than the +[Adafruit Learning System](https://learn.adafruit.com/category/circuitpython) +on their website. diff --git a/zh/tutorials/1.0/configuration.md b/zh/tutorials/1.0/configuration.md new file mode 100644 index 0000000..21a2a46 --- /dev/null +++ b/zh/tutorials/1.0/configuration.md @@ -0,0 +1,43 @@ +--- +layout: default +title: Advanced Configuration +i18n: en +--- + +# Advanced Configuration + +There's nothing advanced about configuring Mu -- you just edit a couple of +files. To find the relevant files you need to check the logs and make a note +of the paths to the files: `settings.json` and `session.json` (see the example +shown below). + +
    + Settings files +
    +
    + +The `session.json` file contains details of Mu's state when you last quit the +editor. It means you can restart Mu where you left off. Mu always overwrites +the content of this file so it's not particularly useful for configuring Mu. +However, it could be a source of useful information when trying to work out +what Mu thinks it should be doing. + +The `settings.json` file is currently used to one "global" setting: the +directory on the user's filesystem in which users should save their files. As +requirements change, more settings may be added to later versions. Each user +of the computer will have their own `settings.json` file. + +If no setting is given, Mu defaults to the `mu_code` directory in the current +user's default home directory (as reported by the host operating system). + +To change the default to something else, you'll need to update the +`settings.json` file to something like this: + +``` +{ + "workspace": "/home/ntoll/src" +} +``` + +The path to the new `workspace` value must be a valid path to a directory that +already exists. Otherwise, Mu will ignore it. diff --git a/zh/tutorials/1.0/debugger.md b/zh/tutorials/1.0/debugger.md new file mode 100644 index 0000000..203050a --- /dev/null +++ b/zh/tutorials/1.0/debugger.md @@ -0,0 +1,109 @@ +--- +layout: default +title: The Visual Debugger +i18n: en +--- + +# The Visual Debugger + +Have you ever wanted to look over the shoulder of Python as it was running +your code? It's a useful ability because you get to compare how you *think* +your code is run with how Python *actually* runs it. This is extraordinarily +helpful if you're trying to find bugs. + +This is what Mu's simple visual debugger allows you to do with Python 3 code. + +The functionality provided by the debugger happens in three places. + +First of all, while in Python 3 mode or when the debugger is running, it's +possible to indicate where Python should pause execution of your script +(giving you an opportunity to look around at that point). This is done with a +breakpoint, indicated by a circle in the margin next to the line-numbers and +toggled on and off by clicking the line number of the desired line. In the +picture below, there's a breakpoint set on line 4, and the debugger will run +your code up until this line, at which point, it will pause: + +
    + A breakpoint +
    +
    + +Secondly, when you click the "Debug" button, two things will happen: your +code will be run under the control of the debugger (as a result, it takes +a little longer than normal for your code to start running), and the buttons +associated with the Python 3 mode will be replaced with the following new +buttons that allow you to navigate your code: + +
    + The Visual Debugger buttons +
    +
    + +Finally, while the debugger is running the inspector pane will appear on the +right hand side and list all the objects Python knows about at that moment in +the execution of your script, along with their associated value. This allows +you to see into the current state of your program and check things are as you +expect them to be. + +
    + The debug inspector +
    +
    + +Just like when you "Run" a program, a new pane will appear below the code area +and above the footer. This will contain any textual input and output for your +program. + +
    +
    Code is Read-Only when Debugging
    +
    +

    To avoid the potential for confusion, when the debugger is running, + you won't be able to change your code. This is because Python's + debugger runs your program as it existed when you clicked the + "Debug" button. If you were able to change it after this point, + there is a possibility that the code the debugger highlights in your + code area doesn't actually exist in the running program.

    +
    +
    + +If you click the "Debug" button without having first set some breakpoints then +the debugger will pause on the first available line. + +In any case, once the debugger has control of your program, it will +highlight the line in your code that Python is about to execute, update the +inspector with the names and values of all the things it curretly knows about +and wait for you to do something. At this point you can use the buttons to +navigate your code. + +The "Stop" button does what you expect: the debugger stops and you're returned +to Python 3 mode. + +The "Continue" button will run your code until either the next breakpoint is +reached (at which point, the debugger will pause again) or your program +finishes. + +The "Step Over" button moves forward through your code one line at a time, no +matter if there is or isn't a breakpoint on the next line. It means you can +watch as each individual line of code effects the state of your program. + +Sometimes the debugger will highlight a line that calls a function. If you were +to "Step Over" this line then you'll move onto the next line without seeing +what the function was doing. But what if you +wanted to step into the function that was called, to see what that block of +code did? Well, that's the purpose of the "Step In" button. Instead of +moving onto the next line in the *current* block of code, it'll skip +into the function and highlight the first block of code *in the function*. + +Of course, you may find yourself in a function which isn't very interesting and +you just want to move back to the line of code that called it (rather than +having to keep pressing "Step Over" until you got to the end of the function). +Happily, this is exactly what the "Step Out" button does: if you're in a +function, it'll move to the line of code immediately *after* the line that +called the current function. + +All these sorts of interactions are illustrated below. + +
    + The Visual Debugger +
    +
    diff --git a/zh/tutorials/1.0/files.md b/zh/tutorials/1.0/files.md new file mode 100644 index 0000000..1e2a0d4 --- /dev/null +++ b/zh/tutorials/1.0/files.md @@ -0,0 +1,39 @@ +--- +layout: default +title: Where are my Files? +i18n: en +--- + +# Where are my Files? + +The quick answer is that they're in the `mu_code` directory in your home +directory. That's all there is to it. + +If you're interested in why, please read on... :-) + +
    + Lost code is in mu_code +
    +
    + +Because feedback from teachers tells us that people easily lose their code +(students will save it somewhere and then forget where they put it -- a 21st +century version of "the dog ate my homework"). + +
    + Lost code is in mu_code +
    +
    + +By having a default location Mu aims to help avoid this problem. + +
    + Lost code is in mu_code +
    +
    + +Of course, when you name a file (either the first time you save it, or when +you double-click the filename on its tab in order to rename it) then you can +use the file selector that pops up to navigate to any other directory. It's +also possible to change directories to find a file elsewhere on disk when you +load a new file. In any case, Mu will always default to `mu_code`. diff --git a/zh/tutorials/1.0/index.html b/zh/tutorials/1.0/index.html new file mode 100644 index 0000000..56a963b --- /dev/null +++ b/zh/tutorials/1.0/index.html @@ -0,0 +1,241 @@ +--- +layout: zh +title: Mu 教程 +i18n: zh +--- + +

    Mu 教程

    + +

    每个教程就像一个自成一体的课程, 解释了 Mu 的一个特定方面, 这样你就有了实现学习和编程目标所需的技能。 + 最重要的是, 它们既有教育意义, 也有娱乐性。

    + +
    +
    +
    + + Start Here + +
    +

    从这里开始！

    +

    这里有开始使用 Mu 及在 Mu 中迈出第一步，你所需要了解的所有基础知识。看了多少就做多少吧！

    +

    阅读 难度：超级简单

    +
    +
    +
    +
    +
    + + Using Modes + +
    +

    使用“模式”

    +

    什么是“模式”？在Mu中该如何使用“模式”？ 我们展示了“模式”如何帮助你制作各种有趣和超棒的项目。

    +

    阅读 难度：超级简单

    +
    +
    +
    +
    +
    + + Files + +
    +

    我的“文件”在哪？

    +

    Mu 将您的所有代码存储在一个特殊的文件夹中，因此它始终位于正确的位置。 本教程介绍了“文件”在哪，以及如何找到它。

    +

    阅读 难度：超级简单

    +
    +
    +
    +
    +
    +
    +
    + + Python 3 Mode + +
    +

    使用标准 Python 3

    +

    Python 是世界上最流行、功能强大且易于学习的编程语言之一。本教程阐述了如何使用 Mu 写 Python。

    +

    阅读 难度：简单

    +
    +
    +
    +
    +
    + + Adafruit Mode + +
    +

    Adafruit 开发板与 Mu

    +

    Adafruit 制作了令人惊叹的小玩意儿，可以运行 + CircuitPython + 的迷你电脑和电路板。本教程阐述了它如何与Mu一起使用。

    +

    阅读 难度：简单

    +
    +
    +
    +
    +
    + + BBC micro:bit Mode + +
    +

    Mu 与 micro:bit

    +

    BBC 的 micro:bit 是一个带有按钮、灯、传感器的小东西。 + 本教程介绍了如何使用 + MicroPython + 给这个小东西编程。

    +

    阅读 难度：简单

    +
    +
    +
    +
    +
    +
    +
    + + Writing Games with Pygame Zero + +
    +

    用 Pygame Zero 写游戏

    +

    使用令人惊叹的 Pygame Zero 和 Mu ，编写电脑游戏非常容易，而且非常有趣。 + 本教程将帮助你入门。

    +

    阅读 难度：简单

    +
    +
    +
    +
    +
    + + A Jupyter REPL + +
    +

    什么是 REPL ？

    +

    REPL （读取Read, 计算Evaluate, 打印Print, 循环Loop）是一种超级强大的途径，可以在 Python 代码中直接与您的计算机对话。 + 本教程将向你展示如何使用REPL。

    +

    阅读 难度：中级

    +
    +
    +
    +
    +
    + + The Debugger + +
    +

    可视化调试器

    +

    调试器允许您运行 Python3 代码，在运行时停止并查看程序的状态，以及一次一行地执行代码。

    +

    阅读 难度：中级

    +
    +
    +
    +
    +
    +
    +
    + + Plotting Data with Mu + +
    +

    使用 Mu 绘制数据

    +

    程序可以生成数据。数据可以通过易于理解的方式被绘制成图像。 + 本教程阐述了 Mu 内置的简单绘图器的工作原理。

    +

    阅读 难度：中级

    +
    +
    +
    +
    +
    + + Keyboard Shortcuts + +
    +

    键盘快捷键

    +

    Mu 的所有功能都可以通过键盘快捷键调用，因此你无需为了移动鼠标而将手从键盘移开。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    +
    + + Logs and Configuration + +
    +

    日志文件和配置

    +

    日志文件是一种在出现错误时，检查 Mu 做了什么的方法。 + 它也可以配置一些 Mu 的行为。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    +
    +
    +
    + + Problems + +
    +

    我发现了一个问题

    +

    正如你将看到的，电脑大多情况下不会工作。本教程将向你展示当你的代码运行失败或者 Mu 崩溃时该如何处理。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    +
    + + Advanced Configuration + +
    +

    进阶配置

    +

    如果您需要更好地控制 Mu 的行为方式或者您想要更改某些默认设置，本教程将介绍所涉及的简单步骤。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    +
    + + Moving On + +
    +

    从 Mu 出发

    +

    Mu 可以帮助你开始入门，迈出编程的第一步。但总会有一天，它会无法满足你的需求。 + 本教程将向你介绍一些可能的下一步。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    diff --git a/zh/tutorials/1.0/logs.md b/zh/tutorials/1.0/logs.md new file mode 100644 index 0000000..fb6d1d1 --- /dev/null +++ b/zh/tutorials/1.0/logs.md @@ -0,0 +1,55 @@ +--- +layout: default +title: Log Files and Configuration +i18n: en +--- + +# Log Files and Configuration + +Sometimes you need to know more about what Mu is doing, in which case you +should check the log files. + +Sometimes you need to let Mu know it should modify its behaviour, in which case +you should configure some simple (yet powerful) settings. + +To access both you should click on the small cog icon in the bottom right of +Mu's window: + +
    + The cog button +
    +
    + +This opens a new dialog window containing three tabs. + +The first tab contains the logs written during the current day: + +
    + The log tab +
    +
    + +To learn what the log entries mean please read our guide for +[how to read logs in Mu](/en/howto/read_logs). + +The second tab allows you to configure various aspects of the environment in +which Python 3 runs your code (so called "environment variables"): + +
    + The envar tab +
    +
    + +To learn how to update the Python 3 environment with environment variables, +read our guide for [how to do this](/en/howto/python3_envars). + +Finally, the third tab contains various settings for flashing code onto a +connected BBC micro:bit: + +
    + The micro:bit tab +
    +
    + +To learn how to change the way code is flashed onto a connected BBC micro:bit, +read our guide for [how to do this](/en/howto/microbit_settings). diff --git a/zh/tutorials/1.0/microbit.md b/zh/tutorials/1.0/microbit.md new file mode 100644 index 0000000..3e7ff96 --- /dev/null +++ b/zh/tutorials/1.0/microbit.md @@ -0,0 +1,84 @@ +--- +layout: default +title: Mu and micro:bit +i18n: en +--- + +# Mu and micro:bit + +The [BBC micro:bit](http://microbit.org/) is a small microcontroller based +computer which was originally created to be handed out to 1 million eleven +year old children in the United Kingdom. The micro:bit runs a special version +of [MicroPython](http://micropython.org/). Mu was originally a contribution by +the [Python Software Foundation](https://www.python.org/psf/) to this endeavour +(along with the browser based editor on the project's website). + +Mu's micro:bit mode ensures all the features you can't get from using the +browser based editor are available and easy to use. These are accessed via +four buttons: + +
    + Buttons from the micro:bit mode +
    +
    + +The "Flash" button puts your Python code onto the connected micro:bit +("flashing" is simply the term for copying code onto a microcontroller). When +you flash the device **all the previous code and data on it is deleted**. If +your code contains an error you'll see a helpful message scroll across the +device's display. + +The process of flashing takes about 10 seconds, as shown below: + +
    + micro:bit flash +
    +
    + +When a micro:bit has MicroPython flashed onto it, it has a small and simple +file system for storing files. Mu's "Files" button makes it easy to access, +put, get and delete files on your device. + +As shown below, clicking on "Files" opens two panes between the text editor and +Mu's footer. The pane on the left lists all the files on the micro:bit, the +pane on the right lists all the files in your `mu_code` directory on your +computer. Drag files between each to copy them. To delete a file on the +micro:bit, right click it and select "Delete". + +
    + micro:bit files +
    +
    + +**NOTE: this functionality only works if you have MicroPython flashed onto the +device.** + +The "REPL" button creates a new pane between the text editor and Mu's footer +which connects to the MicroPython REPL **on the micro:bit device**. The term +"REPL" is an acronym and stands for “Read, Evaluate, Print, Loop”, which +succinctly describes what the panel does for you. It reads interactive lines of +Python which you type, evaluates what these may mean, prints out any result it +has for you and then loops back to wait for your next Python instruction. + +
    + micro:bit repl +
    +
    + +As you can see from the example above, using MicroPython's REPL is like having +a conversation with the micro:bit in Python. Anything you can do in a regular +Python script, you can do in the REPL. It's a fun way to playfully explore the +capabilities of MicroPython on the micro:bit. Go on, have a play! (HINT: there +are lots of Easter eggs built into MicroPython on the micro:bit... can you find +them..?) + +Finally, the "Plotter" button opens Mu's plotter. If your micro:bit is +outputting tuples of numbers via the serial connection, the plotter will +display them as a graph. This is incredibly useful for visualising any data you +might be measuring via the micro:bit. For more information read the +[tutorial about Mu's plotter](plotter). + +
    + micro:bit plotter +
    +
    diff --git a/zh/tutorials/1.0/modes.md b/zh/tutorials/1.0/modes.md new file mode 100644 index 0000000..9aae0fe --- /dev/null +++ b/zh/tutorials/1.0/modes.md @@ -0,0 +1,91 @@ +--- +layout: default +title: Using Modes +i18n: en +--- + +# Using Modes + +Mu is a modal editor. + +All this means is that Mu behaves differently depending on the currently +selected mode. Modes make it easy to customise the way Mu behaves while also +simplifying Mu: rather than trying to provide every possible feature all at +once, modes organise related features and capabilities together. + +As you need to use different sorts of features, change modes by simply clicking +on the "Modes" button (shown below) found as the top left button in Mu. + +Simple! + +
    + The Mode button +
    +
    + +Once clicked a menu, like the one shown below, allows you to select the mode +you wish to use. Just double-click on the required mode, or highlight the mode +and click OK. If you want to back out, click cancel. + +
    + The Mode selector +
    +
    + +## Available Modes + +
    +
    + Adafruit Logo +
    +
    +

    Adafruit

    +

    Adafruit make extraordinarily + awesome boards for embedded development. Many of these boards run + Adafruit's own flavour of MicroPython + called CircuitPython.

    +

    The Adafruit mode understands how to interact with and connect to + Adafruit's boards.

    +
    +
    +
    +
    + Microbit Logo +
    +
    +

    BBC micro:bit

    +

    The BBC micro:bit is a small + computing device for young coders that is capable of running MicroPython. + Mu was originally created as volunteer led effort as part of the Python + Software Foundation's contribution to the project.

    +

    The micro:bit mode understands how to interact with and connect to + a micro:bit.

    +
    +
    +
    +
    + PyGameZero Logo +
    +
    +

    PyGame Zero

    +

    The PyGame Zero + project makes it very easy to write graphical games using Python.

    +

    The PyGame Zero mode understands how to play such games and where to + store game assets like images, sounds and music used in such games.

    +
    +
    +
    +
    + Python Logo +
    +
    +

    Python 3

    +

    Python is one of the world's most + popular professional programming + languages. You use applications written in Python every day! Python is also + very easy to learn for beginner programmers.

    +

    The Python 3 mode provides the tools you need to get started, including + a simple to use visual debugger that helps you watch your code is doing + as it is running.

    +
    +
    diff --git a/zh/tutorials/1.0/moving-on.md b/zh/tutorials/1.0/moving-on.md new file mode 100644 index 0000000..e1d20a2 --- /dev/null +++ b/zh/tutorials/1.0/moving-on.md @@ -0,0 +1,37 @@ +--- +layout: default +title: Moving on from Mu +i18n: en +--- + +# Moving on from Mu + +Mu was created to help you take your first steps in programming with Python. +We want you to learn all you can with Mu, but there will come a time when you +need to graduate to a more advanced code editor. + +Here are some suggestions for what to explore next: + +* [Jupyter Notebooks](https://jupyter.org/) are an amazing way to create an + interactive narrative with code, multi-media and traditional prose. The + REPL in Python 3 mode is a simplified version of a Jupyter notebook, so + project Jupyter should immediately feel familiar. They also have a + wonderfully friendly community. +* [Atom](https://atom.io/) is a free and simple code editor with lots of + useful *optional* features. Made by the folks at GitHub, it works with many + different programming languages and on all the platforms supported by Mu. +* [Visual Studio Code](https://code.visualstudio.com/) is a powerful yet easy + to use cross platform code editor for many different programming languages. + Microsoft have done a great job in supporting Python and + you'll find it comes with more advanced versions of all the features of Mu. +* [PyCharm](https://www.jetbrains.com/pycharm/) is advertised as a Python + IDE (integrated development environment -- i.e. it has lots of bells and + whistles) for professional developers. Apparently there is a simplified + educational version, although I've heard mixed reviews from teachers about + how good it is. + +Finally, please remember that creating software is a collaborative process. +Be open to the ideas of others, show respect for their time, efforts and +feelings and be considerate to your peers. + +Good luck! :-) diff --git a/zh/tutorials/1.0/pgzero.md b/zh/tutorials/1.0/pgzero.md new file mode 100644 index 0000000..32a7ed6 --- /dev/null +++ b/zh/tutorials/1.0/pgzero.md @@ -0,0 +1,51 @@ +--- +layout: default +title: Games with PyGame Zero +i18n: en +--- + +# Games with PyGame Zero + +[PyGameZero](https://pygame-zero.readthedocs.io/en/stable/) is a beginner +friendly wrapper around the powerful [PyGame](http://pygame.org/) +library for writing video games using Python. It's extraordinarily easy to +write an entertaining game in only a few lines of Python code with PyGameZero. +For example, the side scrolling chasing game shown in the video below is only +400 lines of Python which were written using Mu. + +
    + +
    + +Mu's PyGameZero mode provides five buttons but we need only describe two: + +The "Play" button knows how to start your game using the PyGameZero framework +and, once clicked, turns into a "Stop" button. When your game starts any +textual input or output will be contained in the pane added between the +text editor and Mu's footer. Most importantly, a new game window created by +PyGameZero will appear on your desktop. This makes it very easy to see, test +and check your game is working how you expected it to! + +
    + PyGameZero play +
    +
    + +The remaining "Images", "Fonts", "Sounds" and "Music" buttons all work in +exactly the same way. Your game will need to include assets such as images (for +sprites, backgrounds and other things in your game), fonts (so you can write +text to the screen in your game), sounds (for sound effects to signal when +something has happened in your game) and music (to create an atmosphere for +your game). Clicking on each of the four buttons opens the directory into which +you should put such game assets (simply drag and drop things into them using +your operating system's file manager). + +
    + PyGameZero images +
    +
    + +Once your game assets are in the right place, PyGameZero makes it +extraordinarily easy to use them in your game! + +Now go [read the PyGameZero documentation](https://pygame-zero.readthedocs.io/en/stable/) and make something fun! diff --git a/zh/tutorials/1.0/plotter.md b/zh/tutorials/1.0/plotter.md new file mode 100644 index 0000000..54acafc --- /dev/null +++ b/zh/tutorials/1.0/plotter.md @@ -0,0 +1,108 @@ +--- +layout: default +title: Plotting Data with Mu +i18n: en +--- + +# Plotting Data with Mu + +The plotter (contributed by [Adafruit](https://adafruit.com/) makes it easy to +visualise numeric data which your code may create. + +The output is in the form of a [line chart](https://en.wikipedia.org/wiki/Line_chart), +with time running along the x (horizontal) axis and your data values plotted +along the y (vertical) axis. + +To activate the plotter in those modes that support it, simply toggle it on or +off by clicking the "Plotter" button. + +When the plotter is active it begins to listen for a *valid* source of data. +This could be your Python program, something in the REPL or serial data +coming from a connected device. + +In all instances the pattern of *valid* data is the same: a Python tuple +containing only numeric data printed to a new line. In case you're wondering, +a tuple in Python is a collection of data enclosed by parentheis, and looks +like this: `(1, 2, 3)`. + +Each item in the tuple will be plotted on a separate line in the line chart. +So, if you have three sources of data, each time you emit a tuple it will have +three numbers in it, one for each source of data. + +
    +
    Do not Create a Data Flood!
    +
    +

    The usual pattern for emitting tuples is to do so in a loop.

    +

    You MUST include a short pause somewhere in your loop + for the plotter to work correctly.

    +

    Otherwise there's a danger that your code will flood the plotter with + data, it won't be able to keep up and will complain.

    +

    The pause can be very small, but it still has to be there. The best + way to achieve this is to use Python's + time.sleep() (measuring in + seconds) or + microbit.sleep() (measuring in + milliseconds) to achieve this.

    +
    +
    + +All of the above will be clear from an example which creates three random +sources of data for the plotter: + +``` +import time +import random + +while True: + # Just keep emitting three random numbers in a Python tuple. + time.sleep(0.05) + print((random.randint(0, 100), random.randint(-100, 0), random.randint(-50, 50))) +``` + +To be clear, the following is **good data**: + +``` +(1, 2, 3) +(2, 3, 4) +(3, 4, 5) +(4, 5, 6) +``` + +These are examples of **bad data**: + +``` +1, 2, 3 +2, 3, 4 +3, 4, 5 +``` + +(Emitting just numbers, rather than numbers **in a tuple**.) + +``` +(1, 2, 3)(2, 3, 4)(3, 4, 5) +``` + +(Emitting tuples, but not on **a new line**.) + +``` +[1, 2, 3] +[2, 3, 4] +[3, 4, 5] +``` + +(Emitting lists, rather than tuples.) + +That's it! This whole process is shown below... + +
    + The plotter +
    +
    + +Finally, [Adafruit](https://adafruit.com/) have done a bunch of awesome videos +presenting how to use the plotter with various sensors. Check this one out +and follow the link to YouTube to watch the rest. + +
    + +
    diff --git a/zh/tutorials/1.0/problems.md b/zh/tutorials/1.0/problems.md new file mode 100644 index 0000000..47e6695 --- /dev/null +++ b/zh/tutorials/1.0/problems.md @@ -0,0 +1,28 @@ +--- +layout: default +title: I've Found a Problem +i18n: en +--- + +# I've Found a Problem + +As you'll know from writing your own code, all software has bugs! + +Mu is no exception and it's likely you may discover some odd behaviour or Mu +may report a problem. + +If this is the case, we've [created a guide to help you submit a bug report](/en/howto/bugs). +We love getting feedback because bug reports help us to improve Mu and make it +easy for our users to contribute back to the project. + +However, before reaching out to us please remember that everyone who works +on Mu is a volunteer. If you encounter a problem please be considerate and show +respect for their time, efforts and feelings. + +We expect everyone (include those submitting bugs) to behave in the spirit of +the [Python Software Foundation's Code of Conduct](https://www.python.org/psf/codeofconduct/). + +To be clear, we love feedback, bug reports and ideas **IF** it is polite, +coherent and comprehensive enough to allow us to make positive changes to +improve Mu for everyone. We will not hesitate to call out, address and take +action against anyone not behaving in the spirit of the code of conduct. diff --git a/zh/tutorials/1.0/python.md b/zh/tutorials/1.0/python.md new file mode 100644 index 0000000..920404f --- /dev/null +++ b/zh/tutorials/1.0/python.md @@ -0,0 +1,87 @@ +--- +layout: default +title: Using Standard Python 3 +i18n: en +--- + +# Using Standard Python 3 + +Python 3 is one of the most popular professional programming languages in the +world. It's also very easy to learn. Mu's Python 3 mode aims to make learning +Python 3 a stress free experience. + +The functionality provided by Python 3 mode is contained in the following four +buttons: + +
    + Buttons from the Python 3 mode +
    +
    + +Taking each button in turn: + +The "Run" button does exactly what you'd expect. It runs the current script. +When this happens the textual input and output of the program is displayed in +a panel between the text editor and Mu's footer. + +When the code is running the "Run" button turns into a "Stop" button. Click +"Stop" to force your code to exit in a clean way. If your code finishes running +before you click "Stop" then you'll be presented with a Python prompt that +allows you to type Python commands to check the end state of your program. If +in doubt, just click "Stop". + +
    + Python 3 mode run +
    +
    + +Clicking "Debug" will start Mu's visual debugger. The debugger starts running +your code (just like the "Run" button) but does so in a special way that +allows you to pause it, look at the state of things in your program and +step through your code so you can follow how Python is interpreting your +program. This is extraordinarily useful if your code has bugs in it. + +
    + Python 3 mode debug +
    +
    + +Read the [tutorial about how to use the visual debugger](debugger) for more +information. + +The "REPL" button opens a new panel between the text editor and Mu's footer. +The term "REPL" is an acronym and stands for "Read, Evaluate, Print, Loop", +which succinctly describes what the panel does for you. It reads interactive +lines of Python which you type, evaluates what these may mean, prints out any +result it has for you and then loops back to wait for your next Python +instruction. + +
    + Python 3 mode REPL +
    +
    + +Put simply, it's like having a chat with your computer in +Python, it's a fabulously useful tool to use for testing things and "playing +around in code" and, because it is in a question and answer form, is a great +way to tell a story in code. The Python 3 REPL is also very powerful with +lots of interesting features to help you poke around. For more information +please read the [tutorial about how to use the REPL](repl). + +Finally, the "Plotter" button opens the plotter pane between the text editor +and Mu's footer. This is an easy way to visualise numeric data that your +program may produce. + +If you're running a program that prints numbers in a Python +tuple (i.e. the output looks like this: `(1, 2, 3)`) then the plotter will +display these numbers as a graph. + +
    + Python 3 mode plotter +
    +
    + +The number of lines in the graph reflect the number of items in the tuple your +program outputs. **Always remember to put a short pause between writing your +Python tuples** (for example, `time.sleep(0.1)`). For more information, please +read the [tutorial about Mu's plotter](plotter). diff --git a/zh/tutorials/1.0/repl.md b/zh/tutorials/1.0/repl.md new file mode 100644 index 0000000..27e414c --- /dev/null +++ b/zh/tutorials/1.0/repl.md @@ -0,0 +1,320 @@ +--- +layout: default +title: What is a REPL? +i18n: en +--- + +# What is a REPL? + +A REPL (say it, "REP-UL") is an interactive way to talk to your computer in +Python. To make this work, the computer does four things: + +1. **R**ead the user input (your Python commands). +2. **E**valuate your code (to work out what you mean). +3. **P**rint any results (so you can see the computer's response). +4. **L**oop back to step 1 (to continue the conversation). + +The term "REPL" is an acronym for Read, Evaluate, Print and Loop because that's +precisely what the computer does..! + +The computer tells you it's waiting for instructions by presenting you with +either three chevrons (`>>>`) or a numbered prompt (`In [1]:`). You just type +your commands and hit return for the computer to evaluate them. + +Programmers use the REPL when they need to "work stuff out". It's a bit like a +jotter where you "rough out" ideas and explore problems. Because of the +instant feedback you get from a REPL it makes it easy to improvise, nose +around and delve into what the computer is doing. Take it form us, this is +one of the most useful features of Mu, and once you're comfortable with the +REPL, you'll wonder how you ever coped without it. + +While all REPLs work in the same way, the features and capabilities of the +REPL will differ depending on which mode you're currently using in Mu. However, +there are two commands that will work on all version of the REPL that will be +incredibly useful: `dir` and `help`. + +The `dir` command tells you what there is. If you use it on its own, it'll tell +you what Python currently knows about: + +``` +>>> dir() +['__annotations__', '__builtins__', '__doc__', '__loader__', '__name__', +'__package__', '__spec__'] +``` + +While this list of names may look mysterious at the moment, if you +create a new variable you'll see it in the list of things Python knows about: + +``` +>>> name = "Nicholas" +>>> dir() +['__annotations__', '__builtins__', '__doc__', '__loader__', '__name__', +'__package__', '__spec__', 'name'] +``` + +But `dir` can do more! If you use it with the name of something Python knows +about, then `dir` will return all the attributes of that thing. For example, +the `name` variable is actually a string object and string objects have all +sorts of useful attributes. If I wanted to know what they were, I'd pass the +`name` object into `dir` like this: + +``` +>>> dir(name) +['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__', +'__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', +'__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__', +'__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', +'__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', +'__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'capitalize', +'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', +'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isdecimal', 'isdigit', +'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', +'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', +'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', +'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', +'upper', 'zfill'] +``` + +That's a lot of attributes! Given the names of some of them, they may +be quite useful. For example, let's say I want to get an upper-case version of +the `name` object. I notice there's an `upper` attribute in the list returned +by `dir` so I need some way to check what it does. This is where `help` comes +into its own. If you pass something Python knows about into `help` it'll +respond with some useful documentation: + +``` +>>> help(name.upper) +Help on built-in function upper: + +upper(...) method of builtins.str instance + S.upper() -> str + + Return a copy of S converted to uppercase. +``` + +The first line tells you that `upper` is a method of the built-in string class. +The second line tells you that the result of calling `upper` results in a new +string (`-> str`). The final line contains a plain-English description of what +`upper` does. So, I should expect it to return an upper-case version of the +value of `name`: + +``` +>>> name.upper() +`NICHOLAS` +``` + +It worked! + +With just the `dir` and `help` command you'll be able to interrogate +and query the whole of Python. + +
    +
    Handy REPL Hot Keys
    +
    +

    It's often the case that you need to repeatedly enter the same chunk + of Python into the REPL. As an aid to users, REPLs often have a command + history function to select earlier commands used in the current session. + To move backwards in time through your command history, tap the up arrow. + Keep tapping to move further back in time. If you go too far, tap the + down arrow to move forwards in time through the command history until you + get a blank line (meaning you're back at the "present").

    +

    Another useful feature is Tab completion. If you type something and + hit the TAB key the REPL will try + to guess what you mean. For example, if I assigned a string like this: + name = "Nicholas" and then typed + na and pressed + TAB the REPL would complete the word + for me as name. + If the REPL cannot find a clear result, it'll display the available + completions. This is very useful if I want to explore the attributes of + an object in the REPL: I type + name. (note the ".") and then press + TAB. + Since there are many attributes which could follow the + . the REPL + lists them all.

    +

    Tab completion is demonstrated below:

    +
    + Tab complete +
    +
    +
    +
    + +Here's another example: let's pretend you need to do some arithmetic, so why +not use the REPL as a calculator? + +``` +>>> 1 + 1 +2 +>>> 10 - 1 +9 +>>> (5 * 5 + 5 ) / 4 +7.5 +``` + +More advanced mathematics may not at first appear possible. However, if we +import the `math` module and use `dir` and `help` we can soon find the things +we may need: + +``` +>>> import math +>>> dir(math) +['__doc__', '__loader__', '__name__', '__package__', '__spec__', 'acos', +'acosh', 'asin', 'asinh', 'atan', 'atan2', 'atanh', 'ceil', 'copysign', 'cos', +'cosh', 'degrees', 'e', 'erf', 'erfc', 'exp', 'expm1', 'fabs', 'factorial', +'floor', 'fmod', 'frexp', 'fsum', 'gamma', 'gcd', 'hypot', 'inf', 'isclose', +'isfinite', 'isinf', 'isnan', 'ldexp', 'lgamma', 'log', 'log10', 'log1p', +'log2', 'modf', 'nan', 'pi', 'pow', 'radians', 'sin', 'sinh', 'sqrt', 'tan', +'tanh', 'tau', 'trunc'] +>>> help(math.sqrt) +Help on built-in function sqrt in module math: + +sqrt(...) + sqrt(x) + + Return the square root of x. + +>>> math.sqrt(12345) +111.1080555135405 +``` + +Just like in "normal" Python you can import modules, assign values to objects, +use functions and create loops: + +``` +>>> import random +>>> names = ['Lisa', 'Kushal', 'Mary', 'Kate', 'Carlos', 'Zander', ] +>>> while True: +... print(random.choice(names)) +... wait = input() +... +Kate +Kate +Zander +Mary +Zander +Kushal +``` + +To break out of the infinite loop, you need to press `CTRL-C`. This will +result in a message that looks like this: + +``` +Traceback (most recent call last): + File "", line 3, in +KeyboardInterrupt +``` + +It's just Python saying it's been interrupted. + +## Python 3 REPL + +
    + Python 3 REPL +
    +
    + +In Python 3 mode, the REPL uses Python to control your computer. + +This version of the REPL is the most powerful. For example, as you type, the +REPL will show you hints for the code you're using. + +Another powerful feature of Python 3's REPL is the ability to embed graphs, if +you have the `matplotlib` module installed (If you have installed Mu via one +of the installers for Windows or OSX, or via `pip` for Python then you will +have `matplotlib` installed). This is really useful for visualising data you +may be working with in the REPL. + +To make this work you should start your REPL session with the +`%matplotlib inline` command. Then it's just a simple case of using Matplotlib +as [described in its documentation](https://matplotlib.org/contents.html). The +code for a very simple example is shown below followed by an example of how it +should look. + +``` +%matplotlib inline +import matplotlib.pyplot as plt +import random +data = [random.randint(0, 100) for i in range(20)] +plt.plot(data) +``` + +
    + Plotting in the Python 3 REPL +
    +
    + +Another useful feature is the ability to save the current REPL "session" as +an HTML (web) page on your local file system. Simply right-click the REPL to +get to the context menu and select "Save as HTML/XML", as shown below: + +
    + Export a REPL session in the Python 3 REPL +
    +
    + +The REPL is actually a part of the amazing +[Jupyter project](https://jupyter.org/) - a way of creating and sharing +documents that contain live code, visualizations and other fun stuff. You can +read more about the REPL's capabilities in the +[project's documentation](https://qtconsole.readthedocs.io/en/stable/). If you +enjoy using the Python 3 REPL you should consider exploring the "full" +non-beginner Jupyter software as your next step. + +
    +
    A Word about MicroPython based REPLs
    +
    +

    The Python 3 REPL, described above, is very powerful.

    +

    Because of the limited resources and processing power of + microcontrollers, the MicroPython based REPLs, described below, have less + features. For example, you cannot embed graphs. However, they are still + remarkably powerful (with TAB completion and command history available in + the usual way) and give you direct access to controlling the connected + board.

    +
    +
    + +## Adafruit REPL + +It's possible to connect to CircuitPython's REPL running on the connected +board. To be very clear, when you use this REPL you're using CircuitPython to +evaluate code *on the connected Adafruit board* rather than the computer +that's running Mu. + +Getting to the REPL is very easy: + +* Click the "Serial" button to open a serial connection to the connected + device. +* Type "CTRL-C" (keyboard interrupt) to stop CircuitPython from continuing with + whatever it is doing. +* Press any key (as instructed). +* Use the REPL! + +These steps are demonstrated below. + +
    + Adafruit REPL +
    +
    + +## BBC micro:bit REPL + +The REPL on the BBC micro:bit is easy to use, just click the "REPL" button as +shown below. + +
    + BBC micro:bit REPL +
    +
    + +Things to try in the micro:bit REPL: + +``` +>>> from microbit import * +>>> display.scroll("Hello from the REPL") +>>> import this +>>> import love +>>> import antigravity +``` + diff --git a/zh/tutorials/1.0/shortcuts.md b/zh/tutorials/1.0/shortcuts.md new file mode 100644 index 0000000..03331f4 --- /dev/null +++ b/zh/tutorials/1.0/shortcuts.md @@ -0,0 +1,164 @@ +--- +layout: default +title: Keyboard Shortcuts +i18n: en +--- + +# Keyboard Shortcuts + +All the features in Mu can be accessed via keyboard shortcuts. Here's how they +work! + +## Common Buttons + +
    +
    CTRL SHIFT M
    +
    Change mode (the same as clicking "Modes").
    +
    CTRL N
    +
    Create a new empty tab (the same as clicking "New").
    +
    CTRL O
    +
    Open a new file (the same as clicking "Open").
    +
    CTRL S
    +
    Save a file (the same as clicking "Save").
    +
    CTRL +
    +
    Zoom in (the same as clicking "Zoom In").
    +
    CTRL -
    +
    Zoom out (the same as clicking "Zoom Out").
    +
    F1
    +
    Toggle themes (the same as clicking "Theme").
    +
    F2
    +
    Check code (the same as clicking "Check").
    +
    CTRL H
    +
    Display help (the same as clicking "Help").
    +
    CTRL Q
    +
    Quit Mu (the same as clicking "Quit").
    +
    + +## Mode Related Buttons + +### Python 3 + +
    +
    F5
    +
    Run / Stop your code (the same as clicking "Run" or "Stop").
    +
    F6
    +
    Debug your code (the same as clicking "Debug").
    +
    CTRL SHIFT I
    +
    Toggle the REPL (the same as clicking "REPL").
    +
    CTRL SHIFT P
    +
    Toggle the Plotter (the same as clicking "Plotter").
    +
    + +### Debugger + +
    +
    SHIFT F5
    +
    Stop debugger (the same as clicking "Stop").
    +
    F5
    +
    Continue running code (the same as clicking "Continue").
    +
    F10
    +
    Step over a line of code (the same as clicking "Step Over").
    +
    F11
    +
    Step into a block of code (the same as clicking "Step In").
    +
    SHIFT F11
    +
    Step out of a block of code (the same as clicking "Step Out").
    +
    + +### PyGame Zero + +
    +
    F5
    +
    Play or stop your game (the same as clicking "Play" or "Stop").
    +
    CTRL SHIFT I
    +
    Show image asset directory (the same as clicking "Images").
    +
    CTRL SHIFT F
    +
    Show font asset directory (the same as clicking "Fonts").
    +
    CTRL SHIFT N
    +
    Show the sound/noise asset directory (the same as clicking "Sounds").
    +
    CTRL SHIFT M
    +
    Show the music asset directory (the same as clicking "Music").
    +
    + +### Adafruit + +
    +
    CTRL SHIFT U
    +
    Toggle the USB serial connection (the same as clicking "Serial").
    +
    CTRL SHIFT P
    +
    Toggle the Plotter (the same as clicking "Plotter").
    +
    + +The following key combinations work in the serial pane: + +
    +
    CTRL SHIFT C
    +
    Copy highlighted text into the clipboard.
    +
    CTRL SHIFT V
    +
    Paste text into the REPL from the clipboard.
    +
    + +### Microbit + +
    +
    F3
    +
    Flash code onto device (the same as clicking "Flash").
    +
    F4
    +
    Toggle the filesystem (the same as clicking "Files").
    +
    CTRL SHIFT I
    +
    Toggle the REPL (the same as clicking "REPL").
    +
    CTRL SHIFT P
    +
    Toggle the Plotter (the same as clicking "Plotter").
    +
    + +The micro:bit's REPL pane understands the following key combinations: + +
    +
    CTRL SHIFT C
    +
    Copy highlighted text into the clipboard.
    +
    CTRL SHIFT V
    +
    Paste text into the REPL from the clipboard.
    +
    + +## Text Editing + +
    +
    CTRL F
    +
    Show the find and replace dialog.
    +
    CTRL K
    +
    Toggle comments for the current or selected lines of code.
    +
    TAB
    +
    Indent the current or selected lines by four spaces.
    +
    SHIFT TAB
    +
    Unindent the current or selected lines by four spaces.
    +
    CTRL Z
    +
    Undo (keep pressing to keep undoing).
    +
    CTRL Y
    +
    Redo (keep pressing to keep redoing).
    +
    CTRL A
    +
    Select all
    +
    CTRL X
    +
    Cut selected text into the clipboard.
    +
    CTRL C
    +
    Copy selected text into the clipboard.
    +
    CTRL V
    +
    Paste text from the clipboard.
    +
    UP, DOWN, LEFT, RIGHT (arrows)
    +
    Move the cursor one character in the specified direction.
    +
    CTRL LEFT / CTRL RIGHT
    +
    Move the cursor one word in the specified direction.
    +
    SHIFT UP / SHIFT DOWN / SHIFT LEFT / SHIFT RIGHT
    +
    Select text in the specified direction.
    +
    CTRL SHIFT LEFT / CTRL SHIFT RIGHT
    +
    Select text one word in the specified direction.
    +
    + +## Miscellaneous Others + +
    +
    CTRL SHIFT S
    +
    Save the current tab with a new name (the same as double clicking the + tab's name).
    +
    CTRL SHIFT D
    +
    Show the admin dialog (the same as clicking the cog in the bottom right + of Mu's window).
    +
    diff --git a/zh/tutorials/1.0/start.md b/zh/tutorials/1.0/start.md new file mode 100644 index 0000000..f14cb2e --- /dev/null +++ b/zh/tutorials/1.0/start.md @@ -0,0 +1,141 @@ +--- +layout: zh +title: Start Here! +i18n: zh +--- + +# 从这里开始! + +**欢迎使用 Mu！** + +Mu是一个为初学者程序员打造的Python代码编辑器。 +这意味着当你学习用 Python 编写代码时，Mu 可以很容易地创建、运行和修改你的 Python 程序。 + +Mu 非常简单易懂。 这是它的界面： + +
    + The first bug +
    +
    + +虽然上面的图片中似乎有很多内容，但如果我们将其分解一下，你会发现 Mu 很容易学习。 + +Mu 的最顶端是标题栏（如下图所示）。 +这可能在您的计算机上看起来有所不同，但它的功能始终相同： +显示你正在使用的 Mu 版本（如果你需要告诉我们你是否发现了Mu的问题，这很有用）以及 您正在编辑的当前 Python 文件的名称。 + +就是这样！ + +
    + The Mu title bar +
    +
    + +接下来是按钮栏： + +
    + The Mu button bar +
    +
    + +如您所见，它包含着一堆圆形按钮。 +如果将鼠标悬停在按钮上（不是点上去啊！），你会看到一个提示信息，其中包含有关按钮功能的更多信息。 +试试吧！ + +大多数的按钮是不变，但有些按钮会根据您当时正在做的事情而改变。 + +这些按钮按分组组合在一起: + +* 模式（Mode）：这个按钮非常重要，它是单独的一组。 + 单击它可以更改 Mu 的当前模式。每种模式都有不同的功能，具体取决于你想要实现的目标。 + 如果您想了解有关模式的更多信息，这里有一份[关于“模式”的教程](modes)供你接下来参考阅读。 + +* 文件系统：这组中的“新建”、“加载”和“保存”按钮，可以让你与电脑硬盘上存储的文件进行交互。 + * 新建（New）：创建一个新的空白文件。 + * 加载（Load）：打开文件选择器来选择要加载到 Mu 的文件。 + * 保存（Save）：将文件保存到你的电脑硬盘中。如果文件还没有命名的话，则会需要你填写一下文件名。 + 如果文件已经命名，则通常每5秒自动保存一次。 + +* 代码操作：这组按钮会根据你当前所使用的模式儿改变。 + 他们为你所写的代码提供了有趣的交互方式。 + 在上面的示例中，“运行(Run)”、“调试(Debug)”、“REPL”和“绘图器(Plotter)”按钮属于这一组。 + 每个模式的按钮详细信息会在每个模式单独的教程中详细讲解。 + +* 显示设置：有时改变 Mu 的外观很重要。 + 这里的三个按钮（“放大(Zoom-in)”、“缩小(Zoom-out)”、“主题(Theme)”） + 可以改变可以改变 Mu 的呈现方式，“放大”和“缩小”按钮可让文本变大或变小。 + 如果你需要协助阅读代码时会非常有用。 + “主题”按钮可以切换三个不同的显示“主题”： + * 日间：一个浅色的主题，看起来很轻松。（就是上面示例中所使用的主题） + * 夜间: 一个深色的主题，可以让你看起来像是好莱坞电影中的程序高手。 + * 高对比度：黑白色的主题，适合那些有特别需求的人的用户界面。 + + 当你重启编辑器时，Mu 会记得你最后使用的主题。 + +* 编辑器支持：“检查(Check)”、“帮助(Help)”和“退出(Quit)”按钮为 Mu 提供了一些途径来帮助你使用 Mu。 + * 检查(Check)：分析您的代码并提出改进建议。 + * 帮助(Help)：在你的默认浏览器中打开 Mu 的帮助页面。 + * 退出(Quit)：退出编辑器。如果你还没保存的话，可能会要求你保存文件。 + +按钮下方是“选项卡”, 显示你已打开的文件, 并突出显示你当前正在处理的文件: + +
    + The tabs in Mu +
    +
    + +*单击选项卡即可切换你当前要编辑的文件*。 + +要关闭文件，只需单击文件选项卡中的“X”。你还可以单击并左右拖动选项卡来重新对他们进行排序。 + +如果要重命名文件, 可以直接*在选项卡中*双击文件名称, 系统将要求您提供新的名字。 + +在选项卡下面是 Mu 里最大和最重要的部分 —— 文本编辑器: + +
    + The text editor in Mu +
    +
    + +这里会显示当前选定的选项卡中的代码。 +当你切换选项卡时，这个区域的代码会随之更改。 +如果你单击这个区域并开始输入，你将会看到你所输入的代码会显示在这里。 +当你输入代码时，Mu 将即时的更改文本颜色，以帮助你读取代码。 +左边一列是行号的显示区域，这些行号信息对 Python 的错误报告会很有用（报错信息一般会包括行号）。 + +最后, 在底部的是页脚。 + +
    + The footer in Mu +
    +
    + +页脚包含三个内容: + +* 在左边是 Mu 向你输出信息的区域。 + 在示例中，Mu 在说：“诶嘿！检查结果显示，没有问题。” +* 右侧的第一项是当前模式的名称。在示例中，Mu 处于 Python 模式。 +* 在最右手边的是一个齿轮图标。如果你点击它, 你会看到一个管理窗口, 在大多数情况下, 你可以安全地忽略它的处在。 + +## 来自 Mu 的问候！ + +让我们用 Mu 创建第一个 Python 程序吧。 + +1. 确保 Mu 处于 Python 3 模式（在页面右下角确认！）。如果不是的话，点击“模式”按钮，双击启用“Python 3”模式。 +2. 单击“新建”按钮, 然后在输入内容之前, 单击“保存”按钮, 并为您的文件指定一个名称 (比如：“hello.py”)。 +3. 在文本区域中输入以下 Python 代码: + ``` + print("Hello from Mu!") + ``` +4. 单击“运行”按钮, 程序的输出将显示在文本编辑器和页脚之间的新的 "输出" 区域中。 +5. 点击“停止”按钮返回编辑你的代码。 + +步骤3、4、5如下所示: + +
    + Hello from Mu! +
    +
    + +恭喜你！你刚刚使用 Mu 编写并运行了第一个 Python 程序。 +接下来, 为什么不了解一下 [Mu 中的模式](modes)呢？ diff --git a/zh/tutorials/index.html b/zh/tutorials/index.html new file mode 100644 index 0000000..56a963b --- /dev/null +++ b/zh/tutorials/index.html @@ -0,0 +1,241 @@ +--- +layout: zh +title: Mu 教程 +i18n: zh +--- + +

    Mu 教程

    + +

    每个教程就像一个自成一体的课程, 解释了 Mu 的一个特定方面, 这样你就有了实现学习和编程目标所需的技能。 + 最重要的是, 它们既有教育意义, 也有娱乐性。

    + +
    +
    +
    + + Start Here + +
    +

    从这里开始！

    +

    这里有开始使用 Mu 及在 Mu 中迈出第一步，你所需要了解的所有基础知识。看了多少就做多少吧！

    +

    阅读 难度：超级简单

    +
    +
    +
    +
    +
    + + Using Modes + +
    +

    使用“模式”

    +

    什么是“模式”？在Mu中该如何使用“模式”？ 我们展示了“模式”如何帮助你制作各种有趣和超棒的项目。

    +

    阅读 难度：超级简单

    +
    +
    +
    +
    +
    + + Files + +
    +

    我的“文件”在哪？

    +

    Mu 将您的所有代码存储在一个特殊的文件夹中，因此它始终位于正确的位置。 本教程介绍了“文件”在哪，以及如何找到它。

    +

    阅读 难度：超级简单

    +
    +
    +
    +
    +
    +
    +
    + + Python 3 Mode + +
    +

    使用标准 Python 3

    +

    Python 是世界上最流行、功能强大且易于学习的编程语言之一。本教程阐述了如何使用 Mu 写 Python。

    +

    阅读 难度：简单

    +
    +
    +
    +
    +
    + + Adafruit Mode + +
    +

    Adafruit 开发板与 Mu

    +

    Adafruit 制作了令人惊叹的小玩意儿，可以运行 + CircuitPython + 的迷你电脑和电路板。本教程阐述了它如何与Mu一起使用。

    +

    阅读 难度：简单

    +
    +
    +
    +
    +
    + + BBC micro:bit Mode + +
    +

    Mu 与 micro:bit

    +

    BBC 的 micro:bit 是一个带有按钮、灯、传感器的小东西。 + 本教程介绍了如何使用 + MicroPython + 给这个小东西编程。

    +

    阅读 难度：简单

    +
    +
    +
    +
    +
    +
    +
    + + Writing Games with Pygame Zero + +
    +

    用 Pygame Zero 写游戏

    +

    使用令人惊叹的 Pygame Zero 和 Mu ，编写电脑游戏非常容易，而且非常有趣。 + 本教程将帮助你入门。

    +

    阅读 难度：简单

    +
    +
    +
    +
    +
    + + A Jupyter REPL + +
    +

    什么是 REPL ？

    +

    REPL （读取Read, 计算Evaluate, 打印Print, 循环Loop）是一种超级强大的途径，可以在 Python 代码中直接与您的计算机对话。 + 本教程将向你展示如何使用REPL。

    +

    阅读 难度：中级

    +
    +
    +
    +
    +
    + + The Debugger + +
    +

    可视化调试器

    +

    调试器允许您运行 Python3 代码，在运行时停止并查看程序的状态，以及一次一行地执行代码。

    +

    阅读 难度：中级

    +
    +
    +
    +
    +
    +
    +
    + + Plotting Data with Mu + +
    +

    使用 Mu 绘制数据

    +

    程序可以生成数据。数据可以通过易于理解的方式被绘制成图像。 + 本教程阐述了 Mu 内置的简单绘图器的工作原理。

    +

    阅读 难度：中级

    +
    +
    +
    +
    +
    + + Keyboard Shortcuts + +
    +

    键盘快捷键

    +

    Mu 的所有功能都可以通过键盘快捷键调用，因此你无需为了移动鼠标而将手从键盘移开。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    +
    + + Logs and Configuration + +
    +

    日志文件和配置

    +

    日志文件是一种在出现错误时，检查 Mu 做了什么的方法。 + 它也可以配置一些 Mu 的行为。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    +
    +
    +
    + + Problems + +
    +

    我发现了一个问题

    +

    正如你将看到的，电脑大多情况下不会工作。本教程将向你展示当你的代码运行失败或者 Mu 崩溃时该如何处理。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    +
    + + Advanced Configuration + +
    +

    进阶配置

    +

    如果您需要更好地控制 Mu 的行为方式或者您想要更改某些默认设置，本教程将介绍所涉及的简单步骤。

    +

    阅读 难度：进阶

    +
    +
    +
    +
    +
    + + Moving On + +
    +

    从 Mu 出发

    +

    Mu 可以帮助你开始入门，迈出编程的第一步。但总会有一天，它会无法满足你的需求。 + 本教程将向你介绍一些可能的下一步。

    +

    阅读 难度：进阶

    +
    +
    +
    +