doc: experimenting with autodoc generation

Observations:

* Type annotations tend to be verbose, for example:

        blink(color1: typing.Union[pblight.Color, pblight.RGB, NoneType], color2: typing.Union[pblight.Color, pblight.RGB, NoneType], pattern: pblight.Pattern) → None

* There seems to be a bug with .. autodata::

source/conf.py

@@ -18,8 +18,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import sys
+sys.path.insert(0, os.path.abspath('../../lib/fake-pybricks'))
 
 # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
@@ -33,9 +33,12 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc',
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
     'sphinx.ext.todo',
-    'sphinx.ext.mathjax']
+    'sphinx.ext.mathjax',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -82,6 +85,12 @@ pygments_style = 'sphinx'
 todo_include_todos = True
 
 
+# -- Autodoc options ------------------------------------------------------
+
+autodoc_member_order = 'bysource'
+autodoc_default_flags = ['members', 'undoc-members']
+
+
 # -- Options for HTML output ----------------------------------------------
 
 if on_rtd:
@@ -189,6 +198,3 @@ texinfo_documents = [
      author, 'Pybricks', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-

source/index.rst

@@ -23,6 +23,7 @@ Welcome to Pybricks's documentation!
    :maxdepth: 2
    :caption: Common modules:
 
+   modpblight
    modutime
 
 

source/modmovehub.rst

@@ -1,22 +1,46 @@
-:mod:`movehub` -- functions related to the LEGO BOOST Move Hub
-==============================================================
+:mod:`movehub` -- The LEGO BOOST Move Hub
+=========================================
 
-Button functions
-----------------
+The LEGO BOOST Move Hub is the "brain" of a robotics kit released in 2017 aimed
+at younger children.
 
-.. function:: get_button()
 
-    Returns ``True`` if the button is pressed, otherwise ``False``.
+The Ports
+---------
 
-LED functions
--------------
+The Move Hub has two I/O ports labeled 'C' and 'D' for connecting sensors and
+motors. There are also two built-in motors that are connected to virtual ports
+'A' and 'B'. The hub itself is also a virtual port for the button, light and
+internal tilt sensor.
 
-.. function:: set_led(color)
+.. autoclass:: movehub.Port
 
-    Sets the LED color. The *color* can be the name of a color (``"red"``,
-    ``"green"``, ``"blue"``, ``"yellow"``, ``"cyan"``, ``"magenta"``,
-    ``"white"``) or ``None`` to turn the LED off. It can also be a tuple with
-    and RGB value, e.g. ``(255, 128, 0)``.
+
+The Button
+----------
+
+There is one button on the Move Hub. 
+
+.. autodata:: movehub.button
+.. FIXME: for some reason this is picking up the doc from the class instead of the doc comment
+
+
+
+The Light
+---------
+
+The light on the Move Hub is an RGB LED that can display just about any color.
+
+.. autodata:: movehub.light
+.. FIXME: for some reason this is picking up the doc from the class instead of the doc comment
+
+
+The Tilt Sensor
+---------------
+
+The Move Hub has a built-in accelerometer.
+
+.. todo:: Nothing implemented for this yet
 
 
 Battery functions

source/modpblight.rst

@@ -0,0 +1,4 @@
+:mod:`pblight` -- module for lights
+===================================
+
+.. automodule:: pblight