Python: add Sphinx doc project

[babeltrace.git] / doc / bindings / python / source / index.rst

diff --git a/doc/bindings/python/source/index.rst b/doc/bindings/python/source/index.rst
new file mode 100644 (file)
index 0000000..99d0f79
--- /dev/null
+++ b/doc/bindings/python/source/index.rst
@@ -0,0 +1,72 @@
+####################################
+Babeltrace |version| Python bindings
+####################################
+
+Generated on |today|.
+
+
+Welcome!
+========
+
+Welcome to `Babeltrace <http://www.efficios.com/babeltrace>`_'s
+Python bindings' documentation!
+
+Babeltrace is a trace format converter. It is able to read and write
+different trace formats, such as the
+`Common Trace Format <http://www.efficios.com/ctf>`_ (CTF).
+Babeltrace also acts as the CTF reference implementation.
+
+The Babeltrace Python bindings rely on the ``libbabeltrace`` library,
+the current public C API of Babeltrace.
+
+
+Installing
+==========
+
+The Python bindings may be enabled when configuring Babeltrace's build::
+
+    ./configure --enable-python-bindings
+
+On Debian and Ubuntu, the Python bindings are available in the
+``python3-babeltrace`` package.
+
+.. note::
+
+   Currently, the Babeltrace Python bindings only works with Python 3.
+
+
+Bindings
+========
+
+The Babeltrace Python bindings are available as a single Python package,
+:py:mod:`babeltrace`.
+
+The Babeltrace Python bindings' API is divided into two parts:
+
+* The :ref:`reader API <reader-api>` is exposed by the
+  :mod:`babeltrace.reader` module, a set of classes used to
+  open a collection of different traces and iterate on their events.
+* The :ref:`CTF writer API <ctf-writer-api>` is exposed by the
+  :mod:`babeltrace.writer` module, which makes it possible to
+  write a complete `CTF <http://www.efficios.com/ctf>`_ trace from
+  scratch.
+
+.. note::
+
+   For backward compatibility reasons, the reader API is imported in the
+   package itself. The CTF writer API is imported in the package itself
+   too, as :mod:`~babeltrace.CTFWriter`. It is, however, strongly
+   recommended to import and use the three modules
+   (:mod:`babeltrace.common`, :mod:`babeltrace.reader`, and
+   :mod:`babeltrace.writer`) explicitly, since there is no long-term
+   plan to maintain the compatibility layer.
+
+**Contents**:
+
+.. toctree::
+   :numbered:
+
+   constants
+   reader
+   writer
+   examples