Migrate to new structure and fix up links. Omits best-practise guide

hamishwillee · hamishwillee · commit e1db3934c3c9 · 2015-12-23T18:33:06.000+11:00
diff --git a/docs/about/index.rst b/docs/about/index.rst
@@ -12,6 +12,7 @@ After reading, you will understand what the kit offers and the opportunities it
 
    overview
    release_notes
+   migrating
    license
 
    
diff --git a/docs/about/migrating.rst b/docs/about/migrating.rst
@@ -19,7 +19,7 @@ The sections below outline the main migration areas.
 Installation
 ============
 
-DKPY 2.0 is now installed from `pip` on all platforms - see :ref:`get-started` for more information.
+DKPY 2.0 is now installed from `pip` on all platforms - see :ref:`installing_dronekit` for more information.
 
 Installation is generally simpler than on DK 1.x because there are far fewer dependencies (both MAVProxy and numpy 
 are no longer needed).
diff --git a/docs/contributing/developer_setup_linux.rst b/docs/contributing/developer_setup_linux.rst
@@ -5,7 +5,8 @@ Building DroneKit-Python on Linux
 ===================================
 
 The setup for *developing* DroneKit-Python on Linux is almost the same as for *using* 
-DroneKit-Python. We therefore recommend that you start by following the instructions in :ref:`Getting Started <getting_started_installing_dronekit_linux>`. 
+DroneKit-Python. We therefore recommend that you start by following the instructions in 
+:ref:`installing_dronekit`. 
 
 When you've got DroneKit and a vehicle (simulated or real) communicating, you can 
 then build and install your own fork of DroneKit, as discussed below.
diff --git a/docs/contributing/developer_setup_windows.rst b/docs/contributing/developer_setup_windows.rst
@@ -11,7 +11,7 @@ Install DroneKit using WinPython command line
 =============================================
 
 
-First set up a command line DroneKit-Python installation using *WinPython*. This process is the same as described in :ref:`Getting Started <get_started_install_dk_windows>`.
+First set up a command line DroneKit-Python installation. We recommend *WinPython* or *ActivePython*, as discussed in :ref:`installing_dronekit`.
 
 
 
diff --git a/docs/develop/coding_standards.rst b/docs/develop/coding_standards.rst
@@ -0,0 +1,14 @@
+.. _coding_standards:
+
+==========================
+Coding Standards
+==========================
+
+DroneKit-Python does not impose (or recommend) a particular set of coding standards
+for third party code.
+
+Internally we run the `YAPF formatter <https://github.com/google/yapf#introduction>`_
+on major releases and we expect contributors to copy the patterns used in similar
+code within the existing code base.
+
+ 
diff --git a/docs/develop/index.rst b/docs/develop/index.rst
@@ -0,0 +1,23 @@
+========================
+Developing with DroneKit 
+========================
+
+DroneKit-Python is primarily intended for use on Linux-based :doc:`companion-computers` that travel 
+on a vehicle and communicate with the autopilot via a serial port. It can also be used 
+on ground-based computers running Linux, Windows or Mac OSX (communicating using WiFi or a telemetry radio). 
+
+During development you'll generally run it on a development computer, communicating with a 
+:doc:`simulated vehicle<sitl_setup>` running on the same machine (via a UDP connection).
+
+This section contains topics explaining how to develop with DroneKit-Python, 
+covering subjects like installation, setting up the target vehicle or simulator, best practices 
+and coding standards.
+
+
+.. toctree::
+    :maxdepth: 1
+
+    installation
+    companion-computers
+    Simulated Vehicle <sitl_setup>
+    coding_standards
diff --git a/docs/develop/installation.rst b/docs/develop/installation.rst
@@ -0,0 +1,35 @@
+.. _installing_dronekit:
+
+===================
+Installing DroneKit
+===================
+
+DroneKit-Python can be installed on a Linux, Mac OSX, or Windows computer that 
+has *Python 2.7* and can install Python packages from the Internet.
+
+It is installed from **pip** on all platforms:
+
+.. code-block:: bash
+
+    pip install dronekit
+
+
+**Installation notes:**
+
+* Mac and Linux require you prefix the command with ``sudo``. 
+* On Linux you may need to first install **pip** and **python-dev**:
+    
+  .. code-block:: bash
+
+      sudo apt-get install python-pip python-dev
+      
+* :doc:`companion-computers` are likely to run on stripped down versions of Linux. Ensure
+  you use a variant that supports Python 2.7 and can install Python packages from the Internet.
+* Windows does not come with Python by default, but there are 
+  `many distributions available <https://www.python.org/download/alternatives/>`_. 
+  We have tested against:
+    
+  * `WinPython 2.7 64bit <http://sourceforge.net/projects/winpython/files/WinPython_2.7/>`_ (see 
+    `these instructions for installation and registration <https://github.com/winpython/winpython/wiki/Installation>`_). This is the most tested version.    
+  * `ActiveState ActivePython 2.7 <http://www.activestate.com/activepython/downloads>`_.
+* Python 3 is not supported.
diff --git a/docs/examples/channel_overrides.rst b/docs/examples/channel_overrides.rst
@@ -24,7 +24,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`). 
+and DroneKit have been set up as described in :ref:`installing_dronekit`). 
 
 In summary, after cloning the repository:
 
diff --git a/docs/examples/create_attribute.rst b/docs/examples/create_attribute.rst
@@ -31,7 +31,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`).
+and DroneKit have been set up as described in :ref:`installing_dronekit`).
 
 In summary, after cloning the repository:
 
diff --git a/docs/examples/drone_delivery.rst b/docs/examples/drone_delivery.rst
@@ -21,7 +21,7 @@ Running the example
 ===================
 
 The example can be run much as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`). The main exception is that you need to 
+and DroneKit have been set up as described in :ref:`installing_dronekit`). The main exception is that you need to 
 install the CherryPy dependencies and view the behaviour in a web browser.
     
 If you're using a simulated vehicle remember to :ref:`disable arming checks <disable-arming-checks>` so 
diff --git a/docs/examples/flight_replay.rst b/docs/examples/flight_replay.rst
@@ -24,7 +24,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`). 
+and DroneKit have been set up as described in :ref:`installing_dronekit`). 
 
 If you're using a simulated vehicle, remember to :ref:`disable arming checks <disable-arming-checks>` so 
 that the example can run.
diff --git a/docs/examples/follow_me.rst b/docs/examples/follow_me.rst
@@ -18,7 +18,7 @@ python language features and libraries (OpenCV, classes, lots of packages etc...
 Running the example
 ===================
 
-DroneKit (for Linux) and the vehicle should be set up as described in :ref:`get-started`.
+DroneKit (for Linux) and the vehicle should be set up as described in :ref:`installing_dronekit`.
 
 Once you've done that:
 
diff --git a/docs/examples/guided-set-speed-yaw-demo.rst b/docs/examples/guided-set-speed-yaw-demo.rst
@@ -33,7 +33,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`).
+and DroneKit have been set up as described in :ref:`installing_dronekit`).
 
 If you're using a simulated vehicle, remember to :ref:`disable arming checks <disable-arming-checks>` so 
 that the example can run.
@@ -382,7 +382,7 @@ At time of writing, acceleration and yaw bits are ignored.
 Testbed settings
 ================
 
-This example has been tested on Windows against SITL running both natively and in a virtual machine (as described in :ref:`get-started`).
+This example has been tested on Windows against SITL running both natively and in a virtual machine (as described in :ref:`installing_dronekit`).
 
 * DroneKit version: 2.0.0rc12
 * ArduPilot version: 3.4.0.
diff --git a/docs/examples/mission_basic.rst b/docs/examples/mission_basic.rst
@@ -23,7 +23,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`).
+and DroneKit have been set up as described in :ref:`installing_dronekit`).
     
 If you're using a simulated vehicle, remember to :ref:`disable arming checks <disable-arming-checks>` so 
 that the example can run.
diff --git a/docs/examples/mission_import_export.rst b/docs/examples/mission_import_export.rst
@@ -23,7 +23,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`).
+and DroneKit have been set up as described in :ref:`installing_dronekit`).
 
 In summary, after cloning the repository:
 
diff --git a/docs/examples/simple_goto.rst b/docs/examples/simple_goto.rst
@@ -31,7 +31,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`).
+and DroneKit have been set up as described in :ref:`installing_dronekit`).
 
 If you're using a simulated vehicle, remember to :ref:`disable arming checks <disable-arming-checks>` so 
 that the example can run.
diff --git a/docs/examples/vehicle_state.rst b/docs/examples/vehicle_state.rst
@@ -15,7 +15,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that 
-the vehicle and DroneKit have been set up as described in :ref:`get-started`).
+the vehicle and DroneKit have been set up as described in :ref:`installing_dronekit`).
 
 If you're using a simulated vehicle remember to :ref:`disable arming checks <disable-arming-checks>` so 
 that the example can run. You can also:
diff --git a/docs/guide/connecting_vehicle.rst b/docs/guide/connecting_vehicle.rst
@@ -0,0 +1,63 @@
+.. _connecting_vehicle:
+.. _get_started_connecting:
+
+=======================
+Connecting to a Vehicle
+=======================
+
+The connection to the vehicle (or multiple vehicles) is set up within the 
+DroneKit script. Scripts import and call the :py:func:`connect() <dronekit.connect>` 
+method. After connecting this returns a :py:class:`Vehicle <dronekit.Vehicle>` 
+object from which you can get/set parameters and attributes, and control vehicle movement:
+
+.. code:: python
+
+    from dronekit import connect
+
+    # Connect to the Vehicle (in this case a UDP endpoint)
+    vehicle = connect('127.0.0.1:14550', wait_ready=True)
+
+The first parameter above specifies the target address (in this case the loopback 
+address for UDP port 14550). See :ref:`get_started_connect_string` for the strings to use for
+other common vehicles. 
+
+:py:func:`connect() <dronekit.connect>` also has arguments for setting the baud rate, whether ``connect()`` returns immediately or waits until vehicle parameters and attributes are populated (:py:func:`wait_ready=True <dronekit.Vehicle.wait_ready>`),
+the length of the connection timeout, and/or to use a :ref:`custom vehicle class <example_create_attribute>`. 
+
+
+.. _get_started_connect_string:
+
+Connection string options
+=========================
+
+The table below shows *connection strings* you can use for some of the more common connection types:
+
+.. list-table::
+   :widths: 10 10
+   :header-rows: 1
+
+   * - Connection type
+     - Connection string
+   * - Linux computer connected to the vehicle via USB
+     - ``/dev/ttyUSB0``
+   * - Linux computer connected to the vehicle via Serial port (RaspberryPi example)
+     - ``/dev/ttyAMA0`` (also set ``baud=57600``)
+   * - SITL connected to the vehicle via UDP
+     - ``127.0.0.1:14550``
+   * - OSX computer connected to the vehicle via USB
+     - ``dev/cu.usbmodem1``
+   * - Windows computer connected to the vehicle via USB (in this case on COM14)
+     - ``com14``
+   * - Windows computer connected to the vehicle using a 3DR Telemetry Radio on COM14
+     - ``com14`` (also set ``baud=57600``)
+
+.. tip::
+
+    The strings above are the same as are used when connecting the MAVProxy GCS. For other options see the 
+    `MAVProxy documentation <http://dronecode.github.io/MAVProxy/html/getting_started/starting.html#master>`_.
+    
+.. note::
+
+    The default baud rate may not be appropriate for all connection types (this may be the cause
+    if you can connect via a GCS but not DroneKit).
+
diff --git a/docs/guide/getting_started.rst b/docs/guide/getting_started.rst
diff --git a/docs/guide/index.rst b/docs/guide/index.rst
diff --git a/docs/guide/quick_start.rst b/docs/guide/quick_start.rst
diff --git a/docs/guide/taking_off.rst b/docs/guide/taking_off.rst
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/examples/simple_goto/simple_goto.py b/examples/simple_goto/simple_goto.py

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ Install DroneKit using WinPython command line`
`11`	`11`	`=============================================`
`12`	`12`
`13`	`13`
`14`		-First set up a command line DroneKit-Python installation using WinPython. This process is the same as described in :ref:`Getting Started <get_started_install_dk_windows>`.
	`14`	+First set up a command line DroneKit-Python installation. We recommend WinPython or ActivePython, as discussed in :ref:`installing_dronekit`.
`15`	`15`
`16`	`16`
`17`	`17`