Merge pull request #90 from RaspberryPiFoundation/dev

Copy edit of the documentation

README.rst

@@ -3,7 +3,7 @@ picozero
 
 |pypibadge| |docsbadge|
 
-A beginner-friendly library for using common electronics components with the Raspberry Pi Pico.
+A beginner-friendly library to help you use common electronics components with the Raspberry Pi Pico.
 
 .. code-block:: python
 
@@ -23,7 +23,7 @@ Beta. There will be bugs and issues. API changes are likely. More devices will b
 Documentation
 -------------
 
-Documentation is available at `picozero.readthedocs.io <https://picozero.readthedocs.io>`_ :
+Documentation is available at `picozero.readthedocs.io <https://picozero.readthedocs.io>`_:
 
 - `Installation and getting started guide <https://picozero.readthedocs.io/en/latest/gettingstarted.html>`_
 - `Recipes and how-to's <https://picozero.readthedocs.io/en/latest/recipes.html>`_
@@ -34,7 +34,7 @@ Code
 
 The code and project is at `github.com/RaspberryPiFoundation/picozero <https://github.com/RaspberryPiFoundation/picozero>`_. 
 
-Issues can be raised at `github.com/RaspberryPiFoundation/picozero/issues <https://github.com/RaspberryPiFoundation/picozero/issues>`_ (see `contributing <https://picozero.readthedocs.io/en/latest/contributing.html>`_).
+Issues can be raised at `github.com/RaspberryPiFoundation/picozero/issues <https://github.com/RaspberryPiFoundation/picozero/issues>`_ (see `Contributing <https://picozero.readthedocs.io/en/latest/contributing.html>`_).
 
 The latest distribution is available at `pypi.org/project/picozero/ <https://pypi.org/project/picozero/>`_.
 

docs/changelog.rst

@@ -12,41 +12,41 @@ Change log
 0.3.0 - 2022-08-12
 ~~~~~~~~~~~~~~~~~~
 
-+ Introduced ``Motor``, ``Robot`` and ``DistanceSensor`` classes.
-+ Renamed ``LED`` factory ``use_pwm`` parameter to ``pwm`` to match other classes. Note - this is an API breaking change. 
++ Introduced ``Motor``, ``Robot``, and ``DistanceSensor`` classes.
++ Renamed ``LED`` factory ``use_pwm`` parameter to ``pwm`` to match other classes. **Note:** This is an API breaking change. 
 + Resolved issue with ``RGBLED`` when not using ``pwm``.
 + Resolved issue where ``blink`` / ``pulse`` rates of ``0`` raised a traceback error.
-+ Other minor bug fixes
-+ Documentation updates
++ Other minor bug fixes.
++ Documentation updates.
 
 0.2.0 - 2022-06-29
 ~~~~~~~~~~~~~~~~~~
 
-+ Pico W compatibility fix for onboard LED
++ Pico W compatibility fix for onboard LED.
 
 0.1.1 - 2022-06-08
 ~~~~~~~~~~~~~~~~~~
 
-+ Minor bug fixes found during testing
-+ Small improvements to exception messages
-+ Added close methods to Speaker and PWMOutputDevice
-+ Added unit tests
-+ Added RGBLED.colour as an alias to RGBLED.color
++ Minor fixes for bugs found during testing.
++ Small improvements to exception messages.
++ Added close methods to Speaker and PWMOutputDevice.
++ Added unit tests.
++ Added RGBLED.colour as an alias to RGBLED.color.
 
 0.1.0 - 2022-04-08
 ~~~~~~~~~~~~~~~~~~
 
-+ Beta release
-+ Documentation update
-+ Minor bug fixes and refactoring
++ Beta release.
++ Documentation updates.
++ Minor bug fixes and refactoring.
 
 0.0.2 - 2022-03-31
 ~~~~~~~~~~~~~~~~~~
 
-+ Bug fixes and documentation updates
++ Bug fixes and documentation updates.
 
 0.0.1 - 2022-03-21
 ~~~~~~~~~~~~~~~~~~
 
-+ Initial alpha release to test installation process
++ Initial alpha release to test installation process.
 

docs/contributing.rst

@@ -1,20 +1,19 @@
 Contributing
 ============
 
-Contributions to the picozero are welcome. Here is some advice.
+Contributions to picozero are welcome. Please keep in mind that picozero is 'lightweight'. It is designed to be easy to use but also needs to run on a microcontroller; please take this into account when considering feature requests or raising issues.
 
-1. picozero is 'lightweight', it is designed to be easy to use but also needs to run on a micro controller, please take this into account when considering feature requests or raising issues.
-2. see below for other stuff!
+For more details, please see the following advice.
 
 Status
 ------
 
-picozero is currently in Beta, pre release 1.0, you should consider the following:
+As picozero is currently in Beta, pre-release 1.0, you should consider the following:
 
 - The API is not yet set, however, this doesn't mean that backwards compatibility is not important! It is a balancing act.
 - Requests for new features will need to be prioritised and responses to feature requests may take some time.
-- Refactoring of the code base is very likely and as a result pull requests may need rework.
-- Issues are likely to exist within the code base, be kind!
+- Refactoring of the code base is very likely and, as a result, pull requests may need rework.
+- Issues are likely to exist within the code base. Be kind!
 
 Suggestions
 -----------
@@ -31,4 +30,4 @@ Pull requests
 
 All pull requests should be based on the `dev <https://github.com/RaspberryPiFoundation/picozero/tree/dev>`_ branch of picozero. 
 
-.. _issue: https://github.com/RaspberryPiFoundation/picozero/issues
+.. _issue: https://github.com/RaspberryPiFoundation/picozero/issues

docs/developing.rst

@@ -13,11 +13,11 @@ To build and deploy picozero, you need to install the dependencies ::
 Build
 -----
 
-1. Update version numbers in the ``setup.py``, ``picozero/__init__.py`` and ``docs/conf.py`` files.
+1. Update version numbers in the ``setup.py``, ``picozero/__init__.py``, and ``docs/conf.py`` files
 
 2. Add release to ``docs/changelog.rst``
 
-3. Run `setup.py` and create a source distribution ::
+3. Run ``setup.py`` and create a source distribution ::
 
     python3 setup.py sdist
 
@@ -27,7 +27,7 @@ Build
 
 5. Push all changes to ``master`` branch
 
-6. Create a `release <https://github.com/RaspberryPiFoundation/picozero/releases>`_ in github and upload ``picozero-#-#-#.tar.gz`` source file to the release.
+6. Create a `release <https://github.com/RaspberryPiFoundation/picozero/releases>`_ in github and upload ``picozero-#-#-#.tar.gz`` source file to the release
 
 Documentation
 -------------
@@ -51,17 +51,17 @@ Documentation can be viewed at `picozero.readthedocs.io`_ and is automatically b
 Tests
 -----
 
-The tests are design to be run on a Raspberry Pi Pico.
+The tests are designed to be run on a Raspberry Pi Pico.
 
-1. Install the `picozero <https://pypi.org/project/picozero/>`_ package.
+1. Install the `picozero <https://pypi.org/project/picozero/>`_ package
 
-2. Install the `micropython-unittest <https://pypi.org/project/micropython-unittest/>`_ package.
+2. Install the `micropython-unittest <https://pypi.org/project/micropython-unittest/>`_ package
 
-3. Copy the ``test_picozero.py`` to the pico.
+3. Copy the ``test_picozero.py`` file to the Pico
 
-4. Run the ``test_picozero.py`` file.
+4. Run the ``test_picozero.py`` file
 
-If a test fails it is helpful to be able to see verbose error messages. To see error messages you need to modify the ``lib/unittest.py`` file on the pico.
+If a test fails, it is helpful to be able to see verbose error messages. To see error messages, you need to modify the ``lib/unittest.py`` file on the Pico.
 
 Locate the following code in the ``run_class`` function::
 
@@ -71,4 +71,4 @@ Locate the following code in the ``run_class`` function::
 Uncomment ``raise``::
 
     # Uncomment to investigate failure in detail
-    raise
+    raise

docs/gettingstarted.rst

@@ -2,52 +2,52 @@
 ..
 .. SPDX short identifier: MIT
 
-Getting Started
+Getting started
 ===============
 
 Requirements
 ------------
 
-A Windows, macOS or Linux computer with the `Thonny Python IDE`_ installed.
+A Windows, macOS, or Linux computer with the `Thonny Python IDE`_ installed.
 
 .. _Thonny Python IDE: https://thonny.org/
 
-You can find information on how to install Thonny on the `Introduction to Raspberry Pi Pico guide`_.
+You can find information on how to install Thonny in the `Introduction to Raspberry Pi Pico guide`_.
 
 .. _Introduction to Raspberry Pi Pico guide: https://learning-admin.raspberrypi.org/en/projects/introduction-to-the-pico/2
 
-Once Thonny is installed you will need to ensure that you are using the latest MicroPython firmware. Details on how to install or update the Raspberry Pi Pico MicroPython firmware can be found on the `guide`_.
+Once Thonny is installed, you will need to ensure that you are using the latest MicroPython firmware. Details on how to install or update the Raspberry Pi Pico MicroPython firmware can be found in the `Pico guide`_.
 
-.. _guide: https://learning-admin.raspberrypi.org/en/projects/introduction-to-the-pico/3
+.. _Pico guide: https://learning-admin.raspberrypi.org/en/projects/introduction-to-the-pico/3
 
 Use the MicroPython interpreter
 -------------------------------
 
-In Thonny, on the bottom right of the screen, there are options for changing the interpreter that you are using. Make sure that **MicroPython (Raspberry Pi Pico)** is selected.
+You can change which interpreter you are using in Thonny by selecting the desired option at the bottom right of the screen. Make sure that **MicroPython (Raspberry Pi Pico)** is selected.
 
 .. image:: images/thonny-switch-interpreter.jpg
 
-Install picozero from PyPi in Thonny
+Install picozero from PyPI in Thonny
 ------------------------------------
 
-To install picozero within Thonny select **Tools** > **Manage packages...**
+To install picozero within Thonny, select **Tools** > **Manage packages...**
 
 .. image:: images/thonny-manage-packages.jpg
 
-Search for `picozero` on PyPi.
+Search for `picozero` on PyPI.
 
 .. image:: images/thonny-packages-picozero.jpg
 
-Click on install to download the package.
+Click on **install** to download the package.
 
 .. image:: images/thonny-install-package.jpg
 
 Other install options
 ---------------------
 
-You can use the Thonny file manager to transfer a ``picozero.py`` file to Raspberry Pi Pico.
+You can use the Thonny file manager to transfer a ``picozero.py`` file to your Raspberry Pi Pico.
 
-From the **View** menu, choose to see files.
+In the **View** menu, ensure that the **Files** option has a tick. This will let you see the files.
 
 .. image:: images/thonny-view-files.jpg
 
@@ -56,11 +56,11 @@ Either clone the picozero `GitHub repository`_ or copy the code from the `picoze
 .. _GitHub repository: https://github.com/RaspberryPiFoundation/picozero
 .. _picozero.py: https://raw.githubusercontent.com/RaspberryPiFoundation/picozero/master/picozero/picozero.py?token=GHSAT0AAAAAABRLTKWZDBSYBE54NJ7AIZ6MYSENI2A
 
-In Thonny, navigate to the cloned directory or location you save the file to find the ``picozero.py`` file.
+In Thonny, navigate to the cloned directory or location you saved the file in and find the ``picozero.py`` file.
 
 .. image:: images/thonny-navigate-downloads.jpg
 
-Right click on the file and select the **Upload to /** option and you should see a copy of the ``picozero.py`` file on Raspberry Pi Pico.
+Right click on the file and select the **Upload to /** option. You should see a copy of the ``picozero.py`` file on the Raspberry Pi Pico.
 
 .. image:: images/thonny-upload-files.jpg
 .. image:: images/thonny-copy-picozero.jpg
@@ -84,25 +84,25 @@ Run a program on your computer
 
 You can choose to run the program from your computer.
 
-Click on the **Run current script button**.
+Click on the **Run current script** button.
 
 .. image:: images/run-current-script.jpg
 
 Choose to save the script on **This computer** and provide a filename.
 
 .. image:: images/save-this-computer.png
 
-Run a program on Raspberry Pi Pico
+Run a program on your Raspberry Pi Pico
 ----------------------------------
 
-You can choose to run the program from Raspberry Pi Pico.
+You can choose to run the program from the Raspberry Pi Pico.
 
-Click on the **Run current script button**.
+Click on the **Run current script** button.
 
 .. image:: images/run-current-script.jpg
 
 Choose to save the script on **Raspberry Pi Pico** and provide a filename.
 
 .. image:: images/save-this-raspberry-pi-pico.png
 
-If you call the file ``main.py`` it will run automatically when the Pico is powered.
+If you call the file ``main.py``, it will run automatically when the Pico is powered on.