More docs

Author: Jisk Attema

.prospector.yml

@@ -24,3 +24,11 @@ pep257:
         D213,  # Multi-line docstring summary should start at the second line
         D404,  # First word of the docstring should not be This
     ]
+
+pylint:
+    disable:
+      - invalid-name
+
+ignore-paths: [
+        docs/
+    ]

docs/basic.rst

@@ -17,3 +17,9 @@ more C-like API:
 
 .. literalinclude:: ../examples/sum_no_iterator.py
 
+More examples
+~~~~~~~~~~~~~
+
+For more examples, see the *examples* and *tests* directories in the repo.
+Examples cover writing to the ringbuffer, reading and writing header data, and dealing with EndOfData.
+EndOfData is used by *dada_dbevent* to send independent datasets through a ringbuffer, instead of a single continuous stream.

docs/conf.py

@@ -27,7 +27,7 @@
 # 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' ]
+extensions = ['sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/genindex.rst

@@ -0,0 +1,4 @@
+Index
+=====
+
+`genindex`

docs/index.rst

@@ -13,10 +13,4 @@ Welcome to psrdada-python's documentation
 
    basic
    apidoc
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
+   genindex

psrdada/__init__.py

@@ -5,6 +5,18 @@
 This package provides a minimal interface to the PSRDada library.
 Exported are the Reader and Writer classes to connect with
 psrdada ring buffers.
+
+Ringbuffers are used to process large data streams, in our case data generated
+by radio telescopes.
+A writer and (mulitple) readers can connect to the buffer and read, process,
+and write data with a minimum of data copies.
+This library exposes the ringbuffer as a Cython memory view, which you can then
+interact with via fi. numpy.
+
+Use cases are:
+    * rapid prototyping
+    * a glue layer to run CUDA kernels
+    * interactive use of the telescope
 """
 
 from psrdada.reader import Reader

psrdada/reader.pyx

@@ -106,11 +106,12 @@ cdef class Reader(Ringbuffer):
     def getNextPage(self):
         """
         Return a memoryview on the next available ringbuffer page.
+        Use *data = np.asarray(page)* to convert it to something more useable.
 
         The read is blocking; it will wait for a page to become available.
 
         .. note:: The view is readonly, and a direct mapping of the ringbuffer page.
-                  So, no memory copies, and no garbage collector.
+                  So, no memory copies, and no garbage collector.  
 
         :returns: a PyMemoryView
         """

psrdada/writer.pyx

@@ -123,6 +123,7 @@ cdef class Writer(Ringbuffer):
         Return a memoryview on the next available ringbuffer page.
 
         The call is blocking; it will wait for a page to become available.
+        Use *data = np.asarray(page)* to convert it to something more useable.
 
         .. note:: The view is a direct mapping of the ringbuffer page.
                   So, no memory copies, and no garbage collector.