From 4e2aec6c35f52a2026cfc06722ebeb2afeda4a41 Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Tue, 29 Dec 2020 14:35:07 +0100 Subject: [PATCH] doc/pupdevices/motor: split examples Now that each device is on its own page, we no longer need to collapse snippets to reduce page size. Now they can just all be at the bottom of the page. This also gives each a dedicated link which is easier when giving support. --- doc/api/pupdevices/dcmotor.rst | 39 ++++---- doc/api/pupdevices/motor.rst | 174 ++++++++++++++++++--------------- 2 files changed, 117 insertions(+), 96 deletions(-) diff --git a/doc/api/pupdevices/dcmotor.rst b/doc/api/pupdevices/dcmotor.rst index 8bba7ad..ecb5e8e 100644 --- a/doc/api/pupdevices/dcmotor.rst +++ b/doc/api/pupdevices/dcmotor.rst @@ -11,24 +11,6 @@ Motors without Rotation Sensors Powered Up motors without rotation sensors. The arrows indicate the default positive direction. -.. toggle-header:: - :header: **Show/hide examples** - - **Example 1: Making the motor move back and forth** - - .. literalinclude:: - ../../../examples/pup/motor_dc/motor_dc_init_basic.py - - **Example 2: Setting the positive direction as counterclockwise** - - .. literalinclude:: - ../../../examples/pup/motor_dc/motor_dc_init_direction.py - - **Example 3: Starting and stopping** - - .. literalinclude:: - ../../../examples/pup/motor_dc/motor_dc_stop.py - .. autoclass:: pybricks._common.DCMotor :noindex: :no-members: @@ -41,3 +23,24 @@ Motors without Rotation Sensors .. automethod:: pybricks._common.DCMotor.brake :noindex: + +Examples +------------------- + +Making the motor move back and forth +************************************ + +.. literalinclude:: + ../../../examples/pup/motor_dc/motor_dc_init_basic.py + +Changing the positive direction +******************************* + +.. literalinclude:: + ../../../examples/pup/motor_dc/motor_dc_init_direction.py + +Starting and stopping +********************* + +.. literalinclude:: + ../../../examples/pup/motor_dc/motor_dc_stop.py diff --git a/doc/api/pupdevices/motor.rst b/doc/api/pupdevices/motor.rst index d3f47ad..8e8e67a 100644 --- a/doc/api/pupdevices/motor.rst +++ b/doc/api/pupdevices/motor.rst @@ -16,44 +16,8 @@ Motors with Rotation Sensors :noindex: :no-members: - .. toggle-header:: - :header: **Show/hide examples** - - **Example 1: Making the motor move back and forth** - - .. literalinclude:: - ../../../examples/pup/motor/motor_init_basic.py - - **Example 2: Using more than one motor** - - .. literalinclude:: - ../../../examples/pup/motor/motor_init_multiple.py - - **Example 3: Setting the positive direction as counterclockwise** - - .. literalinclude:: - ../../../examples/pup/motor/motor_init_direction.py - - **Example 4: Using gears** - - .. literalinclude:: - ../../../examples/pup/motor/motor_init_gears.py - .. rubric:: Measuring - .. toggle-header:: - :header: **Show/hide examples** - - **Example 1: Measuring the angle and speed** - - .. literalinclude:: - ../../../examples/pup/motor/motor_measure.py - - **Example 2: Resetting the measured angle** - - .. literalinclude:: - ../../../examples/pup/motor/motor_reset_angle.py - .. automethod:: pybricks.pupdevices.Motor.speed .. automethod:: pybricks.pupdevices.Motor.angle @@ -62,14 +26,6 @@ Motors with Rotation Sensors .. rubric:: Stopping - .. toggle-header:: - :header: **Show/hide example** - - **Example: Stopping the motor in different ways** - - .. literalinclude:: - ../../../examples/pup/motor/motor_stop.py - .. automethod:: pybricks.pupdevices.Motor.stop .. automethod:: pybricks.pupdevices.Motor.brake @@ -78,40 +34,6 @@ Motors with Rotation Sensors .. rubric:: Action - .. toggle-header:: - :header: **Show/hide examples** - - **Example 1: Basic usage of all action methods** - - .. literalinclude:: - ../../../examples/pup/motor/motor_action_basic.py - - **Example 2: Using the** ``then`` **argument to change how a motor stops** - - .. literalinclude:: - ../../../examples/pup/motor/motor_action_then.py - - **Example 3: Using the** ``wait`` **argument to run motors in parallel** - - .. literalinclude:: - ../../../examples/pup/motor/motor_action_wait.py - - **Example 4: Waiting for two actions to complete in parallel** - - .. literalinclude:: - ../../../examples/pup/motor/motor_action_wait_advanced.py - - **Example 5: Running a motor until a mechanical endpoint** - - .. literalinclude:: - ../../../examples/pup/motor/motor_until_stalled.py - - **Example 6: Centering a steering mechanism** - - .. literalinclude:: - ../../../examples/pup/motor/motor_until_stalled.py - - .. automethod:: pybricks.pupdevices.Motor.run .. automethod:: pybricks.pupdevices.Motor.run_time @@ -134,3 +56,99 @@ Motors with Rotation Sensors .. FIXME: above should point to pupdevices but inherited class attributes do not work yet (https://github.com/sphinx-doc/sphinx/issues/741). + + +Initialization Examples +----------------------- + +Making the motor move back and forth +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_init_basic.py + +Initializing multiple motors +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_init_multiple.py + +Setting the positive direction as counterclockwise +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_init_direction.py + +Using gears +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_init_gears.py + +Measurement Examples +----------------------- + +Measuring the angle and speed +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_measure.py + +Resetting the measured angle +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_reset_angle.py + + +Movement Examples +----------------------- + +Basic usage of all run methods +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_action_basic.py + +Stopping ongoing movements in different ways +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_stop.py + +Using the ``then`` argument to change how a run command stops +************************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_action_then.py + +Stall Examples +----------------------- + +Running a motor until a mechanical endpoint +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_until_stalled.py + +Centering a steering mechanism +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_until_stalled.py + + +Parallel Movement Examples +-------------------------- + +Using the ``wait`` argument to run motors in parallel +********************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_action_wait.py + +Waiting for two parallel actions to complete +******************************************************* + +.. literalinclude:: + ../../../examples/pup/motor/motor_action_wait_advanced.py