Merge pull request #195 from mavlink/pr-docs

Generate API docs

Author: JonasVautherin

README.md

@@ -6,12 +6,17 @@ This is the Python wrapper for MAVSDK.
 
 The Python wrapper is based on a gRPC client communicating with the gRPC server written in C++. To use the Python wrapper the gRPC server called "backend" needs to be running on the same system. The wrapper is essentially auto-generated from the message definitions ([proto files](https://github.com/mavlink/MAVSDK-Proto)).
 
+
 ## Important Notes
 
 - Python 3.6+ is required (because the wrapper is based on [asyncio](https://docs.python.org/3.7/library/asyncio.html)).
 - You may need to run `pip3` instead of `pip` and `python3` instead of `python`, depending of your system defaults.
 - Auterion has a [Getting started with MAVSDK-Python](https://auterion.com/getting-started-with-mavsdk-python/) guide if you're a beginner and not sure where to start.
 
+## API Reference docs
+
+-> [API Reference documentation](http://mavsdk-python-docs.s3-website.eu-central-1.amazonaws.com/).
+
 ## Install using pip from PyPi
 
 To install mavsdk-python, simply run:
@@ -65,7 +70,6 @@ First install the protoc plugin (`protoc-gen-dcsdk`):
 ```
 cd proto/pb_plugins
 pip3 install -r requirements.txt
-pip3 install -e .
 ```
 
 You can check that the plugin was installed with `$ which protoc-gen-dcsdk`, as it should now be in the PATH.
@@ -85,6 +89,14 @@ Run the following helper script. It will generate the Python wrappers for each p
 ./other/tools/run_protoc.sh
 ```
 
+### Generate the API documentation
+
+```
+pip3 install sphinx numpydoc
+make -C mavsdk html
+```
+
+
 ### Update `mavsdk_server` version
 
 [MAVSDK_SERVER_VERSION](./MAVSDK_SERVER_VERSION) contains exactly the tag name of the `mavsdk_server` release corresponding to the version of MAVSDK-Python. When the [proto](./proto) submodule is updated here, chances are that `mavsdk_server` should be updated, too. Just edit this file, and the corresponding binary will be downloaded by the `setup.py` script (see below).

mavsdk/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

mavsdk/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

mavsdk/source/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'MAVSDK-Python'
+copyright = '2020, Jonas Vautherin, Julian Oes'
+author = 'Jonas Vautherin, Julian Oes'
+
+# The full version, including alpha/beta/rc tags
+release = '0.7.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# 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',
+    'sphinx.ext.napoleon'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'nature_adapted'
+html_theme_path = ["."]
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['nature_adapted/static']

mavsdk/source/index.rst

@@ -0,0 +1,66 @@
+.. MAVSDK-Python documentation master file, created by
+   sphinx-quickstart on Sat May 30 10:40:26 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+|
+
+.. image:: nature_adapted/static/sdk_logo_full.png
+   :alt: MAVSDK logo
+   :scale: 30%
+
+MAVSDK-Python API reference
+===========================
+
+
+.. toctree::
+   :maxdepth: 5
+   :caption: Contents:
+
+   system
+   plugins/index
+
+Important Notes
+---------------
+
+- Python 3.6+ is required.
+- You may need to run ``pip3`` instead of ``pip`` and ``python3`` instead of ``python``, depending of your system defaults.
+- Auterion has a _Getting started with MAVSDK-Python: https://auterion.com/getting-started-with-mavsdk-python/ guide if you're a beginner and not sure where to start.
+
+Install using pip from PyPi
+---------------------------
+
+To install simply run:
+
+  pip3 install mavsdk
+
+
+The package contains ``mavsdk_server`` already (previously called "backend"), which is started automatically when connecting (e.g. ``await drone.connect()``). Have a look at the examples to see it used in practice. It will be something like:
+
+  python
+  from mavsdk import System
+
+  ...
+
+  drone = System()
+  await drone.connect(system_address="udp://:14540")
+
+
+Note: ``System()`` takes two named parameters: ``mavsdk_server_address`` and ``port``. When left empty, they default to ``None`` and ``50051``, respectively, and ``mavsdk_server -p 50051`` is run by ``await drone.connect()``. If ``mavsdk_server_address`` is set (e.g. to "localhost"), then ``await drone.connect()`` will not start the embedded ``mavsdk_server`` and will try to connect to a server running at this address. This is useful for platforms where ``mavsdk_server`` does not come embedded, for debugging purposes, and for running ``mavsdk_server`` in a place different than where the MAVSDK-Python script is run.
+
+Run the examples
+----------------
+
+Once the package has been installed, the examples can be run:
+
+  examples/takeoff_and_land.py
+
+The examples assume that the embedded ``mavsdk_server`` binary can be run. In some cases (e.g. on Raspberry Pi), it may be necessary to run ``mavsdk_server`` manually, and therefore to set ``mavsdk_server_address='localhost'`` as described above.
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

mavsdk/source/nature_adapted/static/sdk_logo_full.png

@@ -0,0 +1,9 @@
+@import url("nature.css");
+
+div.related {
+    background-color: #f26622;
+}
+
+div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 {
+    background-color: #cccccc;
+}

mavsdk/source/nature_adapted/static/style.css

@@ -0,0 +1,3 @@
+[theme]
+inherit = nature
+stylesheet = style.css

mavsdk/source/nature_adapted/theme.conf

@@ -0,0 +1,8 @@
+Action
+====
+
+.. automodule:: mavsdk.generated.action
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :exclude-members: translate_from_rpc, translate_to_rpc

mavsdk/source/plugins/action.rst

@@ -0,0 +1,8 @@
+Calibration
+====
+
+.. automodule:: mavsdk.generated.calibration
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :exclude-members: translate_from_rpc, translate_to_rpc