Add docs page on port name constants (#585)

WasabiFan · dwalton76 · commit 338c48d1e520 · 2018-12-31T11:55:35.000-05:00
diff --git a/docs/port-names.rst b/docs/port-names.rst
@@ -0,0 +1,38 @@
+.. _port-names:
+
+Port names
+==========
+
+Classes such as :py:class:`ev3dev2.motor.Motor` and those based on
+:py:class:`ev3dev2.sensor.Sensor` accept parameters to specify which port the
+target device is connected to. This parameter is typically caled ``address``.
+
+The following constants are available on all platforms:
+
+.. rubric:: Output
+
+- ``ev3dev2.motor.OUTPUT_A``
+- ``ev3dev2.motor.OUTPUT_B``
+- ``ev3dev2.motor.OUTPUT_C``
+- ``ev3dev2.motor.OUTPUT_D``
+
+.. rubric:: Input
+
+- ``ev3dev2.sensor.INPUT_1``
+- ``ev3dev2.sensor.INPUT_2``
+- ``ev3dev2.sensor.INPUT_3``
+- ``ev3dev2.sensor.INPUT_4``
+
+Additionally, on BrickPi3, the ports of up to four stacked BrickPi's can be
+referenced as `OUTPUT_E` through `OUTPUT_P` and `INPUT_5` through `INPUT_16`.
+
+.. rubric:: Example
+
+.. code-block:: python
+
+   from ev3dev2.motor import LargeMotor, OUTPUT_A, OUTPUT_B
+   from ev3dev2.sensor import INPUT_1
+   from ev3dev2.sensor.lego import TouchSensor
+
+   m = LargeMotor(OUTPUT_A)
+   s = TouchSensor(INPUT_1)
diff --git a/docs/ports.rst b/docs/ports.rst
@@ -1,5 +1,8 @@
 Lego Port
 =========
 
+The `LegoPort` class is only needed when manually reconfiguring input/output
+ports. Most users can ignore this page.
+
 .. autoclass:: ev3dev2.port.LegoPort
     :members:
diff --git a/docs/spec.rst b/docs/spec.rst
@@ -1,17 +1,8 @@
 API reference
 =============
 
-Each class in ev3dev module inherits from the base :py:class:`ev3dev2.Device` class.
-
-.. autoclass:: ev3dev2.Device
-
-.. autofunction:: ev3dev2.list_device_names
-
-.. autofunction:: ev3dev2.list_devices
-
-.. autofunction:: ev3dev2.motor.list_motors
-
-.. autofunction:: ev3dev2.sensor.list_sensors
+Device interfaces
+-----------------
 
 .. rubric:: Contents:
 
@@ -26,4 +17,21 @@ Each class in ev3dev module inherits from the base :py:class:`ev3dev2.Device` cl
     sound
     display
     ports
+    port-names
     wheels
+
+
+Other APIs
+----------
+
+Each class in ev3dev module inherits from the base :py:class:`ev3dev2.Device` class.
+
+.. autoclass:: ev3dev2.Device
+
+.. autofunction:: ev3dev2.list_device_names
+
+.. autofunction:: ev3dev2.list_devices
+
+.. autofunction:: ev3dev2.motor.list_motors
+
+.. autofunction:: ev3dev2.sensor.list_sensors
