Initial set of updates to documentation for Stretch (#411)

* Initial set of updates to documentation for Stretch

* Remove "indices and tables" section of home page

It seemed pretty useless to me given that we have the "tree" immediately
above it.

* Update navbar link

* Improvements to motor docs

* Add a new SpeedInteger for percentage and improve related docs

* More motor docs improvements

* README updates

* Continue iterating on motor docs and readme

* Update sensor docs page

* Add new section to Stretch upgrade guide on new features

* Attempt to fix docs build

* Add WIP section

* Clean-up and new drive example

* Add docs build validation to Travis

* Update README.rst

Author: WasabiFan

.gitignore

@@ -7,4 +7,6 @@ dist
 RELEASE-VERSION
 ev3dev2/version.py
 build
+_build/
+docs/_build/
 .idea

.travis.yml

@@ -1,13 +1,17 @@
 language: python
 python:
 - 3.4
+cache: pip
 sudo: false
+git:
+  depth: 100
 install:
-- pip install Pillow
-- pip install evdev
+- pip install -q Pillow evdev Sphinx sphinx_bootstrap_theme recommonmark evdev
+- pip install -q -r ./docs/requirements.txt
 script:
 - chmod -R g+rw ./tests/fake-sys/devices/**/*
 - ./tests/api_tests.py
+- sphinx-build -nW -b html ./docs/ ./docs/_build/html
 deploy:
   provider: pypi
   user: Denis.Demidov

README.rst

@@ -25,122 +25,126 @@ your EV3 or other ev3dev device as explained in the `ev3dev Getting Started guid
 Make sure that you have a kernel version that includes ``-10-ev3dev`` or higher (a
 larger number). You can check the kernel version by selecting "About" in Brickman
 and scrolling down to the "kernel version". If you don't have a compatible version,
-`upgrade the kernel before continuing`_. Also note that if the ev3dev image you downloaded
-was created before September 2016, you probably don't have the most recent version of this
-library installed: see `Upgrading this Library`_ to upgrade it.
+`upgrade the kernel before continuing`_.
 
-Once you have booted ev3dev and `connected to your EV3 (or Raspberry Pi / BeagleBone)
-via SSH`_, you should be ready to start using ev3dev with Python: this library
-is included out-of-the-box. If you want to go through some basic usage examples,
-check out the `Usage Examples`_ section to try out motors, sensors and LEDs.
-Then look at `Writing Python Programs for Ev3dev`_ to see how you can save
-your Python code to a file.
+Usage
+-----
 
-Make sure that you look at the `User Resources`_ section as well for links
-to documentation and larger examples.
+To start out, you'll need a way to work with Python. We recommend the
+`ev3dev Visual Studio Code extension`_. If you're interested in using that,
+check out our `Python + VSCode introduction tutorial`_ and then come back
+once you have that set up.
 
-Usage Examples
---------------
+Otherwise, you can can work with files `via an SSH connection`_ with an editor
+such as `nano`_, use the Python interactive REPL (type ``python3``), or roll
+your own solution. If you don't know how to do that, you are probably better off
+choosing the recommended option above.
 
-To run these minimal examples, run the Python3 interpreter from
-the terminal using the ``python3`` command:
+The template for a Python script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
+Every Python program should have a few basic parts. Use this template
+to get started:
 
-  $ python3
-  Python 3.4.2 (default, Oct  8 2014, 14:47:30)
-  [GCC 4.9.1] on linux
-  Type "help", "copyright", "credits" or "license" for more information.
-  >>>
+.. code-block:: python
 
-The ``>>>`` characters are the default prompt for Python. In the examples
-below, we have removed these characters so it's easier to cut and
-paste the code into your session.
+   #!/usr/bin/env python3
+   from ev3dev2.motor import LargeMotor, OUTPUT_A, SpeedPercent
+   from ev3dev2.sensor.lego import TouchSensor
+   from ev3dev2.led import Leds
 
-Required: Import the library
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   # TODO: Add code here
 
-If you are using an EV3 brick (which is the case for most users), add the
-following to the top of your file:
+The first line should be included in every Python program you write
+for ev3dev. It allows you to run this program from Brickman, the graphical
+menu that you see on the device screen. The other lines are import statements
+which give you access to the library functionality. You will need to add
+additional classes to the import list if you want to use other types of devices
+or additional utilities.
 
-.. code-block:: python
+You should use the ``.py`` extension for your file, e.g. ``my-file.py``.
 
-  import ev3dev.ev3 as ev3
+Important: Make your script executable (non-Visual Studio Code only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you are using a BrickPi, use this line:
+To be able to run your Python file, **your program must be executable**. If
+you are using the `ev3dev Visual Studio Code extension`_, you can skip this step,
+as it will be automatically performed when you download your code to the brick.
 
-.. code-block:: python
+**To mark a program as executable from the command line (often an SSH session),
+run** ``chmod +x my-file.py``.
 
-  import ev3dev.brickpi as ev3
+You can now run ``my-file.py`` via the Brickman File Browser or you can run it
+from the command line by preceding the file name with ``./``: ``./my-file.py``
 
 Controlling the LEDs with a touch sensor
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This code will turn the left LED red whenever the touch sensor is pressed, and
-back to green when it's released. Plug a touch sensor into any sensor port and
-then paste in this code - you'll need to hit ``Enter`` after pasting to complete
-the loop and start the program.  Hit ``Ctrl-C`` to exit the loop.
+back to green when it's released. Plug a touch sensor into any sensor port before
+trying this out.
 
 .. code-block:: python
 
-  ts = ev3.TouchSensor()
+  ts = TouchSensor()
+  leds = Leds()
+
   while True:
-      ev3.Leds.set_color(ev3.Leds.LEFT, (ev3.Leds.GREEN, ev3.Leds.RED)[ts.value()])
+      if ts.is_pressed:
+          leds.set_color(leds.led_groups.LEFT, leds.led_colors.GREEN)
+      else:
+          leds.set_color(leds.led_groups.LEFT, leds.led_colors.RED)
 
 Running a motor
 ~~~~~~~~~~~~~~~
 
-Now plug a motor into the ``A`` port and paste this code into the Python prompt.
-This little program will run the motor at 500 ticks per second, which on the EV3
-"large" motors equates to around 1.4 rotations per second, for three seconds
-(3000 milliseconds).
+This will run a LEGO Large Motor at 75% of maximum speed for 5 rotations.
 
 .. code-block:: python
 
-  m = ev3.LargeMotor('outA')
-  m.run_timed(time_sp=3000, speed_sp=500)
+  m = LargeMotor(OUTPUT_A)
+  m.on_for_rotations(SpeedPercent(75), 5)
 
-The units for ``speed_sp`` that you see above are in "tacho ticks" per second.
-On the large EV3 motor, these equate to one tick per degree, so this is 500
-degress per second.
+You can also run a motor for a number of degrees, an amount of time, or simply
+start it and let it run until you tell it to stop. Additionally, other units are
+also available. See the following pages for more information:
 
+- http://python-ev3dev.readthedocs.io/en/stretch/motors.html#ev3dev.motor.Motor.on_for_degrees
+- http://python-ev3dev.readthedocs.io/en/stretch/motors.html#units
 
+Driving with two motors
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Using text-to-speech
-~~~~~~~~~~~~~~~~~~~~
-
-If you want to make your robot speak, you can use the `Sound.speak` method:
+The simplest drive control style is with the `MoveTank` class:
 
 .. code-block:: python
 
-  ev3.Sound.speak('Welcome to the E V 3 dev project!').wait()
+    drive = MoveTank(OUTPUT_A, OUTPUT_B)
 
-**To quit the Python REPL, just type** ``exit()`` **or press** ``Ctrl-D`` **.**
+    # drive in a turn for 5 rotations of the outer motor
+    # the first two parameters are percentages; they can also be unit classes.
+    drive.on_for_rotations(50, 75, 10)
+    
+    # drive in a different turn for 3 rotations of the outer motor
+    drive.on_for_rotations(60, 30, 3)
 
-Make sure to check out the `User Resources`_ section for more detailed
-information on these features and many others.
+There are also `MoveSteering` and `MoveJoystick` classes which provide different
+styles of control. Take a look at the corresponding documentation for more detail.
 
-Writing Python Programs for Ev3dev
-----------------------------------
+Using text-to-speech
+~~~~~~~~~~~~~~~~~~~~
 
-Every Python program should have a few basic parts. Use this template
-to get started:
+If you want to make your robot speak, you can use the ``Sound.speak`` method:
 
 .. code-block:: python
 
-   #!/usr/bin/env python3
-   from ev3dev.ev3 import *
+  from ev3dev2.sound import Sound
 
-   # TODO: Add code here
+  sound = Sound()
+  sound.speak('Welcome to the E V 3 dev project!').wait()
 
-The first two lines should be included in every Python program you write
-for ev3dev. The first allows you to run this program from Brickman, while the
-second imports this library.
-
-When saving Python files, it is best to use the ``.py`` extension, e.g. ``my-file.py``.
-To be able to run your Python code, **your program must be executable**. To mark a
-program as executable run ``chmod +x my-file.py``. You can then run ``my-file.py``
-via the Brickman File Browser or you can run it from the command line via ``$ ./my-file.py``
+Make sure to check out the `User Resources`_ section for more detailed
+information on these features and many others.
 
 User Resources
 --------------
@@ -150,6 +154,11 @@ Library Documentation
     You can always go there to get information on how you can use this
     library's functionality.
 
+Demo Code
+    There are several demo programs that you can run to get acquainted with
+    this language binding. The programs are available at
+    https://github.com/ev3dev/ev3dev-lang-python-demo
+
 ev3python.com
     One of our community members, @ndward, has put together a great website
     with detailed guides on using this library which are targeted at beginners.
@@ -171,11 +180,6 @@ Support
     what you are trying to do and what you have tried. The issue template
     is in place to guide you through this process.
 
-Demo Code
-    There are several demo programs that you can run to get acquainted with
-    this language binding. The programs are available at
-    https://github.com/ev3dev/ev3dev-lang-python-demo
-
 Upgrading this Library
 ----------------------
 
@@ -196,16 +200,6 @@ Python Package Index
     libraries that others have written, including the `latest version of
     this package`_.
 
-The ev3dev Binding Specification
-    Like all of the language bindings for ev3dev_ supported hardware, the
-    Python binding follows the minimal API that must be provided per
-    `this document`_.
-
-The ev3dev-lang Project on GitHub
-    The `source repository for the generic API`_ and the scripts to automatically
-    generate the binding. Only developers of the ev3dev-lang-python_ binding
-    would normally need to access this information.
-
 Python 2.x and Python 3.x Compatibility
 ---------------------------------------
 
@@ -222,17 +216,13 @@ Python 3 and this is the only version that will be supported from here forward.
 .. _ev3dev-getting-started: http://www.ev3dev.org/docs/getting-started/
 .. _upgrade the kernel before continuing: http://www.ev3dev.org/docs/tutorials/upgrading-ev3dev/
 .. _detailed instructions for USB connections: ev3dev-usb-internet_
-.. _connected to your EV3 (or Raspberry Pi / BeagleBone) via SSH: http://www.ev3dev.org/docs/tutorials/connecting-to-ev3dev-with-ssh/
+.. _via an SSH connection: http://www.ev3dev.org/docs/tutorials/connecting-to-ev3dev-with-ssh/
 .. _ev3dev-usb-internet: http://www.ev3dev.org/docs/tutorials/connecting-to-the-internet-via-usb/
 .. _our Read the Docs page: http://python-ev3dev.readthedocs.org/en/stable/
-.. _source repository for the generic API: ev3dev-lang_
 .. _ev3python.com: http://ev3python.com/
 .. _FAQ: http://python-ev3dev.readthedocs.io/en/stable/faq.html
-.. _ev3dev-lang: https://github.com/ev3dev/ev3dev-lang
 .. _ev3dev-lang-python: https://github.com/rhempel/ev3dev-lang-python
 .. _our Issues tracker: https://github.com/rhempel/ev3dev-lang-python/issues
-.. _this document: wrapper-specification_
-.. _wrapper-specification: https://github.com/ev3dev/ev3dev-lang/blob/develop/wrapper-specification.md
 .. _EXPLOR3R: demo-robot_
 .. _demo-robot: http://robotsquare.com/2015/10/06/explor3r-building-instructions/
 .. _demo programs: demo-code_
@@ -246,3 +236,6 @@ Python 3 and this is the only version that will be supported from here forward.
 .. _pypi: https://pypi.python.org/pypi
 .. _latest version of this package: pypi-python-ev3dev_
 .. _pypi-python-ev3dev: https://pypi.python.org/pypi/python-ev3dev
+.. _ev3dev Visual Studio Code extension: https://github.com/ev3dev/vscode-ev3dev-browser
+.. _Python + VSCode introduction tutorial: https://github.com/ev3dev/vscode-hello-python
+.. _nano: http://www.ev3dev.org/docs/tutorials/nano-cheat-sheet/

docs/conf.py

@@ -30,6 +30,7 @@
 
 import sphinx_bootstrap_theme
 from recommonmark.parser import CommonMarkParser
+from recommonmark.transform import AutoStructify
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -135,7 +136,7 @@
 html_theme_options = {
         'bootswatch_theme': 'yeti',
         'navbar_links' : [
-            ("GitHub", "https://github.com/rhempel/ev3dev-lang-python", True)
+            ("GitHub", "https://github.com/ev3dev/ev3dev-lang-python", True)
             ]
         }
 
@@ -311,3 +312,16 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+autodoc_member_order = 'bysource'
+
+nitpick_ignore = [
+    ('py:class', 'ev3dev2.display.FbMem'),
+    ('py:class', 'ev3dev2.button.ButtonBase')
+]
+
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+            'enable_eval_rst': True,
+            }, True)
+    app.add_transform(AutoStructify)

docs/index.rst

@@ -1,23 +1,11 @@
-.. python-ev3dev documentation master file, created by
-   sphinx-quickstart on Sat Oct 31 20:38:27 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 .. include:: ../README.rst
 
 .. rubric:: Contents
 
 .. toctree::
    :maxdepth: 3
 
+   upgrading-to-stretch
    spec
    rpyc
    faq
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-