Merge pull request #149 from hamishwillee/tmp_contributing_updates

mrpollo · mrpollo · commit dbcb5a143031 · 2015-06-09T21:27:46.000-07:00
Update contributions section with how to set up a dev environment
diff --git a/docs/about/index.rst b/docs/about/index.rst
@@ -2,17 +2,16 @@
 Introducing DroneKit-Python
 ===========================
 
-This section provides an overview of DroneKit-Python's functionality, licensing, supported companion computers, and how you can contribute.
+This section provides an overview of DroneKit-Python's functionality, licensing, and supported companion computers.
 
 After reading, you will understand what the kit offers and the opportunities it provides. You will also know where to go if you have further questions for suggestions for improvement.
 
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 4
 
    overview
    release_notes
-   contributing
    license
 
    
diff --git a/docs/contributing/contributions_api.rst b/docs/contributing/contributions_api.rst
@@ -0,0 +1,50 @@
+.. _contributing_api:
+
+=======================
+Contributing to the API
+=======================
+
+This article provides a high level overview of how to contribute changes to the DroneKit-Python source code.
+
+.. tip:: 
+
+    We highly recommend that changes and ideas are `discussed with the project team 
+    <https://github.com/diydrones/dronekit-python/issues>`_ before starting work! 
+
+
+Submitting changes
+==================
+
+Contributors should fork the main `diydrones/dronekit-python/ <https://github.com/diydrones/dronekit-python>`_ 
+repository and contribute changes back to the project master branch using pull requests
+
+* Changes should be :ref:`tested locally <contributing-test-code>` before submission.
+* Changes to the public API should be :ref:`documented <contributing-to-documentation>` (we will provide subediting support!)
+* Pull requests should be as small and focussed as possible to make them easier to review.
+* Pull requests should be rebased against the main project before submission to make integration easier.
+
+
+
+.. _contributing-test-code:
+
+Test code
+=========
+
+Test code should be used to verify new and changed functionality. Changes to DroneKit can be tested locally by 
+rebuilding your git branch and running it against SITL. The links below provide information on how 
+to set up a development environment on your development computer:
+
+* :ref:`dronekit_development_linux`
+* :ref:`dronekit_development_windows`
+
+.. note:: At time of writing (June 2015) we do not yet have formal acceptance tests (unit tests, system tests).
+
+We recommend that you provide your test script as a gist, and run any the 
+:ref:`DroneKit-Python Examples <example-toc>` that are relevant.
+ 
+For example, the addition of a new API item for retrieving a vehicle attribute would need test code for 
+getting, setting (if applicable) and printing the attribute. An easy way to create this would be to 
+update and run :ref:`example-vehicle-state`.
+
+
+
diff --git a/docs/contributing/contributions_documentation.rst b/docs/contributing/contributions_documentation.rst
@@ -1,41 +1,37 @@
-.. _contributing:
-
-============
-Contributing
-============
-
-DroneKit is an open-source project. We welcome any contribution that will improve the API — adding new features and making it easier to use. 
-
-
-Getting started
-================
-
-The dronekit-python project is `hosted on Github here <https://github.com/diydrones/dronekit-python/>`_. This where you get the source code, and is the best place to raise `bug reports and enhancement suggestions <https://github.com/diydrones/dronekit-python/issues>`_.
-
-.. tip:: Before starting new work, first create an issue in Github so it can be tracked and discussed! 
+.. _contributing-to-documentation:
 
-In addition to creating defect reports, a good starting point is to work on the `open issues <https://github.com/diydrones/dronekit-python/issues>`_ on Github. In particular, :ref:`documentation issues <contributing-to-documentation>` can be resolved without a deep knowledge of the code, and will help you learn more about the project.
+=================================
+Contributing to the Documentation
+=================================
 
+One of the best ways that you can help is by improving this documentation.  Here we explain
+the documentation system, how to build the documents locally, and how to submit your changes.
 
-How to submit changes
-=====================
 
-Contributors should fork the main project Github repository and contribute changes back to the project using pull requests:
+Documentation system overview
+=============================
 
-* Ideas should be discussed with the project team first (using an issue) 
-* Pull requests should be as small and focussed as possible to make them easier to review
-* Rebase your code against the main project before submission to make integration easier
+The documentation source files are `stored in Github <https://github.com/diydrones/dronekit-python/tree/master/docs>`_. 
+The content is written in plain-text files (file-extension :file:`.rst`) using 
+`reStructuredText <http://sphinx-doc.org/rest.html>`_ markup, and is compiled into HTML using the 
+`Sphinx Documentation Generator <http://sphinx-doc.org/index.html>`_. 
 
+Submitting changes
+==================
 
+The process and requirements for submitting changes to the documentation are **the same** as when 
+:ref:`contributing to the source code <contributing_api>`. 
 
-.. _contributing-to-documentation:
+As when submitting source code you should fork the main project Github repository and 
+contribute changes back to the project using pull requests. The changes should be tested
+locally (by :ref:`building the docs <contributing_building_docs>`) before being submitted.
 
-Contributing to the API documentation
-=====================================
+See :ref:`contributing_api` for more information. 
 
-One of the best ways that you can help is by improving this documentation.  
+.. _contributing_building_docs:
 
-The documentation source files are `stored in Github <https://github.com/diydrones/dronekit-python/tree/master/docs>`_. The content is written in plain-text files (file-extension :file:`.rst`) using `reStructuredText <http://sphinx-doc.org/rest.html>`_ markup, and is compiled into HTML using the `Sphinx Documentation Generator <http://sphinx-doc.org/index.html>`_. As with any other contributions to this project, you should fork the main project Github repository and contribute changes back to the project using pull requests.
+Building the docs
+=================
 
 We've made it very easy to get started by providing a `Vagrant <https://www.vagrantup.com/>`_ based setup for :program:`Sphinx`. Using :program:`Vagrant` you can work with source files on your host machine using a familiar :program:`git` client and text editor, and then invoke :program:`Sphinx` in the :program:`Vagrant` VM to compile the source to HTML.
 
@@ -88,14 +84,20 @@ The instructions below explain how to get the documentation source, and build it
 	vagrant resume    #Restart the VM
 	vagrant ssh -c "cd /vagrant/docs && make html"   #Build files when needed.
 
-	
-* After making changes, follow the normal process to submit them to the project (i.e.commit and push them to your fork on Github, and then create a pull request on Github to the project repository).
 
-	
-	
-		
-		
+Style guide
+===========
+
+.. tip:: 
+
+    This guide is evolving. The most important guidance we can give is 
+    to *copy the existing style of reference, guide and example material*!
+
 
+#. Use US English for spelling.
 
+#. Use emphasis sparingly (italic, bold, underline). 
 
+#. Use `Sphinx semantic markup <http://sphinx-doc.org/markup/inline.html#other-semantic-markup>`_ to mark up *types* of text (key-presses, file names etc.)
 
+#. Use double backticks (``) around ``inline code`` items.
diff --git a/docs/contributing/developer_setup_linux.rst b/docs/contributing/developer_setup_linux.rst
@@ -0,0 +1,41 @@
+.. _dronekit_development_linux:
+
+===================================
+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>`. 
+
+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.
+
+
+Fetch and build DroneKit source
+===============================
+
+#. Fork the `dronekit-python <https://github.com/diydrones/dronekit-python>`_ project on Github.
+
+#. Run the following commands to clone and build DroneKit (in the directory of your choice):
+  
+   .. code:: bash
+
+       git clone https://github.com/<your_fork_of_dronekit>/dronekit-python.git
+       cd ./dronekit-python
+       sudo python setup.py build
+       sudo python setup.py install
+
+	   
+Updating DroneKit
+=================
+
+Navigate to your local git fork, pull the latest version, and rebuild/install:
+
+.. code:: bash
+
+    cd ./<path-to-your-dronekit-fork>/dronekit-python
+    git pull
+    sudo python setup.py build
+    sudo python setup.py install
+
+
diff --git a/docs/contributing/developer_setup_windows.rst b/docs/contributing/developer_setup_windows.rst
@@ -0,0 +1,43 @@
+.. _dronekit_development_windows:
+
+===================================
+Building DroneKit-Python on Windows
+===================================
+
+The setup for *developing* DroneKit-Python on Windows is almost the same as for *using* 
+DroneKit-Python. We therefore recommend that you start by following the instructions in the :ref:`get-started` and/or 
+:ref:`quick-start`. 
+
+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.
+
+
+Fetch and build DroneKit source
+===============================
+
+#. Fork the `dronekit-python <https://github.com/diydrones/dronekit-python>`_ project on Github.
+
+#. Open the *WinPython Command Prompt*. Run the following commands to clone and build DroneKit (in the directory of your choice):
+  
+   .. code:: bash
+
+       git clone https://github.com/<your_fork_of_dronekit>/dronekit-python.git
+       cd dronekit-python
+       python setup.py build
+       python setup.py install
+
+
+	   
+Updating DroneKit
+=================
+
+Navigate to your local git fork, pull the latest version, and rebuild/install:
+
+.. code:: bash
+
+    cd <path-to-your-dronekit-fork>/dronekit-python
+    git pull
+    python setup.py build
+    python setup.py install
+
+
diff --git a/docs/contributing/getting_started.rst b/docs/contributing/getting_started.rst
@@ -0,0 +1,18 @@
+.. _contributing_getting_started:
+
+=======================
+How you can Contribute
+=======================
+
+One of the best ways you can contribute is to simply *use the API* and share your 
+`bug reports and enhancement suggestions on Github <https://github.com/diydrones/dronekit-python/issues>`_. 
+These can cover anything: from APIs that don't work properly through to needed features or documentation.
+
+If you want to take a more active role, then a good place to start is with the project's
+`open issues <https://github.com/diydrones/dronekit-python/issues>`_ on Github. In particular, 
+:ref:`documentation issues <contributing-to-documentation>` can be resolved without a deep knowledge of the code, 
+and will help you learn more about the project.
+
+If there is a feature that you want to add, then please do so! Before you start we highly recommend that 
+you first create an issue in Github so it can be tracked and discussed! 
+
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
@@ -0,0 +1,24 @@
+.. _contributing:
+
+============
+Contributing
+============
+
+DroneKit is an open-source project. We welcome any contribution that will improve the API and make it easier to use. 
+
+The articles below explain some of the :ref:`opportunities <contributing_getting_started>` for working on the project, how to :ref:`contribute to the API <contributing_api>` or the :ref:`documentation <contributing-to-documentation>`, and how to set up a :ref:`development environment on Linux <dronekit_development_linux>` or :ref:`Windows <dronekit_development_windows>`.
+
+
+.. toctree::
+    :maxdepth: 1
+
+    getting_started
+    contributions_api
+    contributions_documentation
+    developer_setup_windows
+    developer_setup_linux
+
+
+
+
+   
diff --git a/docs/guide/getting_started.rst b/docs/guide/getting_started.rst
@@ -34,6 +34,7 @@ Installing DroneKit
 
 *DroneKit* can be installed on Linux, Windows and Mac OSX. 
 
+.. _getting_started_installing_dronekit_linux:
 
 Installing DroneKit on Linux
 ----------------------------
@@ -92,7 +93,7 @@ You will need remove *python-dateutil* as the installation comes bundled with a
 
 The steps to install this package and our add-on modules are:
 
-1. Run the correct `WinPython installer <http://sourceforge.net/projects/winpython/files/WinPython_2.7/2.7.6.4/>`_ for your platform (win32 vs win64)
+1. Run the correct `WinPython installer <http://sourceforge.net/projects/winpython/files/WinPython_2.7/2.7.6.4/>`_ (**v2.7**) for your platform (win32 vs win64)
 
 2. Register the python that came from *WinPython* as the preferred interpreter for your machine:
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -21,5 +21,6 @@ Contents:
     quick_start
     guide/index
     examples/index
+    contributing/index
     API Reference <automodule>
 
diff --git a/docs/quick_start.rst b/docs/quick_start.rst
@@ -73,7 +73,7 @@ Install Python and DroneKit
 
 Install the *WinPython* package and DroneKit on your Windows computer:
 
-5. Run the correct `WinPython installer <http://sourceforge.net/projects/winpython/files/WinPython_2.7/2.7.6.4/>`_ for your platform (win32 vs win64)
+5. Run the correct `WinPython installer <http://sourceforge.net/projects/winpython/files/WinPython_2.7/2.7.6.4/>`_ (**v2.7**) for your platform (win32 vs win64)
 
 6. Open the folder where you installed WinPython, run *WinPython Control Panel* and choose **Advanced/Register Distribution** (to register it as the preferred interpreter for your machine):
 
