doc: add figure numbers and reference labels

laurensvalk · laurensvalk · commit d593831386ab · 2019-03-01T15:00:36.000+01:00
fixes #131
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -95,6 +95,9 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+# Figure numbering
+numfig = True
+
 # -- Autodoc options ------------------------------------------------------
 
 autodoc_member_order = 'bysource'
diff --git a/doc/source/examples/color_sorter.rst b/doc/source/examples/color_sorter.rst
@@ -1,16 +1,17 @@
 Color Sorter
 =====================
 
-This example program for the color sorter lets you scan colored Technic beams using the Color Sensor. 
+This example program for the color sorter (:numref:`fig_color_sorter`) lets you scan colored Technic beams using the Color Sensor. 
 
 Scan the colored beams one by one and add them to the tray. A beep confirms that it has registered the color. When the tray is full or when you press the center button, the robot will start distributing the Technic bricks by color. 
 
 You can find building instructions for the color sorter on the `LEGO Education website <https://le-www-live-s.legocdn.com/sc/media/lessons/mindstorms-ev3/building-instructions/ev3-model-core-set-color-sorter-c778563f88c986841453574495cb5ff1.pdf>`_.
 
+.. _fig_color_sorter:
 
 .. figure:: ../images/color_sorter.jpg
    :width: 90 %
-   :alt: overview
+   :alt: color_sorter
    :align: center
 
    Color Sorter
diff --git a/doc/source/examples/robot_arm_h25.rst b/doc/source/examples/robot_arm_h25.rst
@@ -1,15 +1,17 @@
 Robot Arm H25
 =====================
 
-This example program makes the robot move the black wheel hub stacks around forever. The robot arm will first initialize and then start moving the hubs around.
+This example program makes the robot (:numref:`fig_robot_arm`) move the black wheel hub stacks around forever. The robot arm will first initialize and then start moving the hubs around.
 
 You can find building instructions for the robot on the `LEGO Education website <https://le-www-live-s.legocdn.com/sc/media/lessons/mindstorms-ev3/building-instructions/ev3-model-core-set-robot-arm-h25-56cdb22c1e3a02f1770bda72862ce2bd.pdf>`_.
 
 Tip: When building the robot, reverse the orientation of the EV3 Brick such that the microSD card is easily accessible.
 
+.. _fig_robot_arm:
+
 .. figure:: ../images/robot_arm.jpg
    :width: 90 %
-   :alt: overview
+   :alt: robot_arm
    :align: center
 
    Robot Arm H25
diff --git a/doc/source/examples/robot_educator.rst b/doc/source/examples/robot_educator.rst
@@ -1,13 +1,15 @@
 Robot Educator
 =====================
 
-This example makes the Robot Educator drive until it sees an obstacle. It then backs up, turns around, and starts driving again.
+This example makes the Robot Educator (:numref:`fig_robot_educator`)  drive until it sees an obstacle. It then backs up, turns around, and starts driving again.
 
 You can find building instructions for the Robot Educator on the `LEGO Education website <https://education.lego.com/en-us/support/mindstorms-ev3/building-instructions#robot>`_.
 
+.. _fig_robot_educator:
+
 .. figure:: ../images/ultrasonic_sensor_driving_base.jpg
    :width: 50 %
-   :alt: overview
+   :alt: robot_educator
    :align: center
 
    Robot Educator with the Ultrasonic Sensor
diff --git a/doc/source/startinstall.rst b/doc/source/startinstall.rst
@@ -23,12 +23,16 @@ To get started, you'll need:
 
 - A mini-USB cable, like the one included with your EV3 set
 
-The typical configuration of this equipment is summarized in the figure below.
+The typical configuration of this equipment is summarized in :numref:`fig_overview`.
+
+.. _fig_overview:
 
 .. figure:: images/overview.png
    :width: 90 %
    :alt: overview
-   :align: center   
+   :align: center
+
+   Setup overview
 
 Preparing your computer
 -----------------------------------------------------------
@@ -38,8 +42,10 @@ You'll write your MicroPython programs using Visual Studio Code. Follow the step
 1. Download `Visual Studio Code <https://code.visualstudio.com/Download>`_.
 2. Follow the on-screen instructions to install the application.
 3. Launch Visual Studio Code.
-4. Open the extensions tab as shown below.
-5. Install and activate the required extension:
+4. Open the extensions tab.
+5. Install the extension as shown in :numref:`fig_store`.
+
+.. _fig_store:
 
 .. figure:: images/store.png
     :alt: store
@@ -65,12 +71,14 @@ To install the MicroPython tools on your microSD card:
 1. Download the `EV3 MicroPython microSD card image <.>`_ and save it in a convenient location. This file is approximately 360 MB. Do **not** open or unzip the file.
 2. Download and install a microSD card flashing tool such as `Etcher <https://www.balena.io/etcher/>`_.
 3. Insert the microSD card into your computer or card reader.
-4. Launch the flashing tool and follow the steps on your screen to install the file you have just downloaded. If you use Etcher, you can follow the instructions in the diagram below:
+4. Launch the flashing tool and follow the steps on your screen to install the file you have just downloaded. If you use Etcher, you can follow the instructions below, as shown in :numref:`fig_etcher`.
 
     a. Select the EV3 MicroPython microSD card image file you have just downloaded.
     b. Select your microSD card. Make sure that the device and size correspond to your microSD card.
     c. Start the flashing process. This may take several minutes. Do not remove the card until the flashing process is complete.
 
+.. _fig_etcher:
+
 .. figure:: images/etcher.png
    :width: 85 %
    :alt: etcher
@@ -88,7 +96,9 @@ You do not need to erase the contents of the microSD card first. This is done au
 Using the EV3 Brick
 -----------------------------------------------------------
 
-Make sure the EV3 Brick is turned off. Insert the microSD card you prepared into the microSD card slot on the EV3 Brick, as shown below.
+Make sure the EV3 Brick is turned off. Insert the microSD card you prepared into the microSD card slot on the EV3 Brick, as shown in :numref:`fig_sd`.
+
+.. _fig_sd:
 
 .. figure:: images/sd.png
    :width: 75 %
@@ -105,7 +115,9 @@ Turn on the EV3 Brick by pressing the dark gray center button.
 
 The boot process may take several minutes. While booting, the EV3 Brick status light turns orange and blinks intermittently, and you'll see a lot of text on the EV3 screen. The EV3 Brick is ready for use when the status light turns green.
 
-To turn the EV3 Brick off, open the shutdown menu with the back button, and then select *Power Off* using the center button, as shown below.
+To turn the EV3 Brick off, open the shutdown menu with the back button, and then select *Power Off* using the center button, as shown in :numref:`fig_onoff`.
+
+.. _fig_onoff:
 
 .. figure:: images/onoff.png
    :width: 65 %
@@ -117,7 +129,9 @@ To turn the EV3 Brick off, open the shutdown menu with the back button, and then
 Viewing motor and sensor values
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-When you're not running a program, you can view motor and sensor values using the device browser, as shown below.
+When you're not running a program, you can view motor and sensor values using the device browser, as shown in :numref:`fig_devicebrowser`.
+
+.. _fig_devicebrowser:
 
 .. figure:: images/devicebrowser.png
    :width: 100 %
diff --git a/doc/source/startrun.rst b/doc/source/startrun.rst
@@ -5,14 +5,16 @@ Now that you've set up your computer and EV3 Brick, you're ready to start writin
 
 To make it easier to create and manage your programs, let's first have a quick look at how MicroPython projects and programs for your EV3 robots are organized.
 
-Programs are organized into *project folders*, as shown below. A project folder is a directory on your computer that contains the main program (**main.py**) and other optional scripts or files. This project folder and all of its contents will be copied to the EV3 Brick, where the main program will be run.
+Programs are organized into *project folders*, as shown in :numref:`fig_projectstructure`. A project folder is a directory on your computer that contains the main program (**main.py**) and other optional scripts or files. This project folder and all of its contents will be copied to the EV3 Brick, where the main program will be run.
 
 This page shows you how to create such a project and how to transfer it to the EV3 Brick.
 
 
+.. _fig_projectstructure:
+
 .. figure:: images/projectstructure.png
    :width: 100 %
-   :alt: alt
+   :alt: projectstructure
    :align: center
 
    A project contains a program called **main.py** and optional resources like sounds or MicroPython modules.
@@ -21,22 +23,26 @@ This page shows you how to create such a project and how to transfer it to the E
 Creating a new project
 -----------------------------------------------------------
 
-To create a new project, open the Pybricks tab and click *create a new project*, as shown below. Enter a project name in the text field that appears and press *Enter*. When prompted, choose a location for this program and confirm by clicking *choose folder*.
+To create a new project, open the Pybricks tab and click *create a new project*, as shown in :numref:`fig_newproject`. Enter a project name in the text field that appears and press *Enter*. When prompted, choose a location for this program and confirm by clicking *choose folder*.
+
+.. _fig_newproject:
 
 .. figure:: images/newproject.png
    :width: 100 %
-   :alt: alt
+   :alt: newproject
    :align: center
 
    Creating a new project. This example is called *getting_started*, but you can choose any name.
 
-When you create a new project, it already includes a file called *main.py*. To see its contents and to modify it, open it from the file browser as shown below. This is where you'll write your programs.
+When you create a new project, it already includes a file called *main.py*. To see its contents and to modify it, open it from the file browser as shown in :numref:`fig_projectoverview`. This is where you'll write your programs.
 
 If you are new to MicroPython programming, we recommend that you keep the existing code in place and add your code to it.
 
+.. _fig_projectoverview:
+
 .. figure:: images/projectoverview.png
    :width: 100 %
-   :alt: alt
+   :alt: projectoverview
    :align: center
 
    Opening the default *main.py* program.
@@ -50,40 +56,45 @@ To be able to transfer your code to the EV3 Brick, you'll first need to connect
 
 - Turn the EV3 Brick on
 - Connect the EV3 Brick to your computer with the mini-USB cable
-- Configure the USB connection as shown:
+- Configure the USB connection as shown in :numref:`fig_connecting`.
+
+.. _fig_connecting:
 
 .. figure:: images/connecting.png
    :width: 100 %
-   :alt: alt
+   :alt: connecting
    :align: center
 
    Configuring the USB connection between the computer and the EV3 Brick
 
 Downloading and running a program
 -----------------------------------------------------------
 
-You can press the F5 key to run the program. Alternatively, you can start it manually by going to the *debug* tab and clicking the green start arrow, as shown below.
+You can press the F5 key to run the program. Alternatively, you can start it manually by going to the *debug* tab and clicking the green start arrow, as shown in :numref:`fig_running`.
 
 When the program starts, a pop-up toolbar allows you to stop the program if necessary. You can also stop the program at any time using the back button on the EV3 Brick.
 
 If your program produces any output with the :mod:`print <.tools>` command, this is shown in the output window.
 
+.. _fig_running:
+
 .. figure:: images/running.png
    :width: 100 %
-   :alt: alt
+   :alt: running
    :align: center
 
    Running a program
 
 Expanding the example program
 -----------------------------------------------------------
 
-Now that you've run the basic code template, you can expand the program to make a motor move. First, attach a Large Motor to Port B on the EV3 Brick, as shown below.
+Now that you've run the basic code template, you can expand the program to make a motor move. First, attach a Large Motor to Port B on the EV3 Brick, as shown in :numref:`fig_firstprogram`.
 
+.. _fig_firstprogram:
 
 .. figure:: images/firstprogram.png
    :width: 100 %
-   :alt: alt
+   :alt: firstprogram
    :align: center
 
    The EV3 Brick with a Large Motor attached to port B.
@@ -99,11 +110,13 @@ This program makes your robot beep, rotate the motor, and beep again with a high
 Managing files on the EV3 Brick
 -----------------------------------------------------------
 
-After you've downloaded a project to the EV3 Brick, you can run, delete, or back up programs stored on it using the device browser:
+After you've downloaded a project to the EV3 Brick, you can run, delete, or back up programs stored on it using the device browser as shown in in :numref:`fig_files`.
+
+.. _fig_files:
 
 .. figure:: images/files.png
    :width: 100 %
-   :alt: alt
+   :alt: files
    :align: center
 
    Using the device browser to manage files on your EV3 Brick
@@ -114,11 +127,13 @@ Running a program without a computer
 
 You can run previously downloaded programs directly from the EV3 Brick.
 
-To do so, find the program using the *file browser* on the EV3 screen and press the center button key to start the program.
+To do so, find the program using the *file browser* on the EV3 screen and press the center button key to start the program as shown in in :numref:`fig_manualrun`.
+
+.. _fig_manualrun:
 
 .. figure:: images/manualrun.png
    :width: 100 %
-   :alt: alt
+   :alt: manualrun
    :align: center
 
    Starting a program using the buttons on the EV3 Brick
