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.
The documentation source files are stored in Github.
The content is written in plain-text files (file-extension
reStructuredText markup, and is compiled into HTML using the
Sphinx Documentation Generator.
The process and requirements for submitting changes to the documentation are the same as when contributing to the source code.
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 building the docs) before being submitted.
See Contributing to the API for more information.
We’ve made it very easy to get started by providing a Vagrant based setup for Sphinx. Using Vagrant you can work with source files on your host machine using a familiar git client and text editor, and then invoke Sphinx in the Vagrant VM to compile the source to HTML.
The instructions below explain how to get the documentation source, and build it using our Vagrant VM:
Install the Vagrant pre-conditions:
Clone your fork of the Github repository anywhere on the host PC:
git clone https://github.com/YOUR-REPOSITORY/dronekit-python.git
Navigate to the root of dronekit-python and start the Vagrant VM:
cd /your-path-to-clone/dronekit-python/ vagrant up
This may take a long time to complete the first time it is run — Vagrant needs to download the virtual machine and then set up Sphinx.
When the VM is running, you can build the source by entering the following command in the prompt:
vagrant ssh -c "cd /vagrant/docs && make html"
The files will be built by Sphinx, and will appear on the host system in
<clone-path>/dronekit-python/docs/_build/html/. To preview, simply open them in a Web browser.
vagrant ssh -c "cd /vagrant/docs && make html" command starts (and closes) an SSH session with the VM. If you plan on building the source a number of times it is much faster to keep the session open:
vagrant ssh # Open an SSH session with the Vagrant VM cd /vagrant/docs # Navigate to the docs root (contains Sphinx configuration files) make html # Build the HTML ... # Repeat "make html" as many time as needed make html exit # Close the SSH session.
When you are finished you can suspend the VM. Next time you need to build more HTML simply restart it (this is a fast operation):
vagrant suspend #Suspend the VM vagrant resume #Restart the VM vagrant ssh -c "cd /vagrant/docs && make html" #Build files when needed.
This guide is evolving. The most important guidance we can give is to copy the existing style of reference, guide and example material!