switching to conda environment for readthedocs (to enable fftw3). doc…

…s updated (using numpy docstrings). added developers guide.

.readthedocs.yml

@@ -5,16 +5,19 @@
 # Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
-
 # Build PDF & ePub
 formats:
   - pdf
   - epub
 
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+conda:
+  file: environment_doc.yml
+
 # Optionally set the version of Python and requirements required to build your docs
 python:
   version: 3.7
@@ -23,3 +26,6 @@ python:
       path: .
       extra_requirements:
         - docs
+
+build:
+  image: latest

docs/api/sigpyproc.Filterbank.rst

@@ -0,0 +1,7 @@
+sigpyproc.Filterbank
+====================
+
+.. automodule:: sigpyproc.Filterbank
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/sigpyproc.FoldedData.rst

@@ -0,0 +1,7 @@
+sigpyproc.FoldedData
+====================
+
+.. automodule:: sigpyproc.FoldedData
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/sigpyproc.FourierSeries.rst

@@ -0,0 +1,7 @@
+sigpyproc.FourierSeries
+=======================
+
+.. automodule:: sigpyproc.FourierSeries
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/sigpyproc.Header.rst

@@ -0,0 +1,7 @@
+sigpyproc.Header
+================
+
+.. automodule:: sigpyproc.Header
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/sigpyproc.HeaderParams.rst

@@ -0,0 +1,7 @@
+sigpyproc.HeaderParams
+======================
+
+.. automodule:: sigpyproc.HeaderParams
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/sigpyproc.Readers.rst

@@ -0,0 +1,7 @@
+sigpyproc.Readers
+=================
+
+.. automodule:: sigpyproc.Readers
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/sigpyproc.TimeSeries.rst

@@ -0,0 +1,7 @@
+sigpyproc.TimeSeries
+====================
+
+.. automodule:: sigpyproc.TimeSeries
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/sigpyproc.Utils.rst

@@ -0,0 +1,7 @@
+sigpyproc.Utils
+===============
+
+.. automodule:: sigpyproc.Utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/sigpyproc.libSigPyProc.rst

@@ -0,0 +1,7 @@
+sigpyproc.libSigPyProc
+======================
+
+.. automodule:: sigpyproc.libSigPyProc
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/dev.rst

@@ -0,0 +1,82 @@
+.. _dev:
+
+Developer guide
+===============
+
+Here we will cover all the steps required to add new functionality to the
+``sigpyproc`` package. To do this, we will first consider adding a new function
+to the :class:`~sigpyproc.Filterbank.Filterbank` class, before going on to extend
+the function to deal with an arbitrary data format.
+
+
+Adding a new function: ``bandpass()``
+-------------------------------------
+**Aim:** Add a new function called bandpass, which will return the total power
+as a function of frequency for our observation.
+
+**Files to be modified:** ``sigpyproc/Filterbank.py``, ``c_src/kernels.hpp``
+, ``c_src/bindings.cpp``.
+
+Step 1: Write the Python part
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The first step is to write the Python side of the function. As this function
+will run on data with both time and frequency resolution,
+it belongs in the :class:`~sigpyproc.Filterbank.Filterbank` class.
+
+.. code-block:: python
+
+    def bandpass(self, gulp=512, **kwargs):
+        bpass_ar = np.zeros(self.header.nchans, dtype="float64")
+        num_samples = 0
+        for nsamps, ii, data in self.readPlan(gulp, **kwargs):
+            lib.getBpass(data, bpass_ar, self.header.nchans, nsamps)
+            num_samples += nsamps
+        bpass_ar = bpass_ar / num_samples
+        return TimeSeries(bpass_ar, self.header.newHeader({"nchans": 1}))
+
+Looking at the important lines, we have:
+Return an instance of the :class:`~sigpyproc.TimeSeries.TimeSeries` class.
+The :class:`~sigpyproc.TimeSeries.TimeSeries` class takes two arguments,
+an instance of :py:obj:`numpy.ndarray` and an instance of
+:class:`~sigpyproc.Header.Header`.
+
+Now we have something similar to a normal :py:obj:`numpy.ndarray`,
+which exports several other methods for convenience.
+
+Step 2: Write the C++ part
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+We called a C++ library function named getBpass. This function belongs in the
+``c_src/kernels.hpp`` file (or anywhere you please, as long as it is properly
+binded with the `pybind11 <https://pybind11.readthedocs.io/>`_ library).
+In ``kernels.hpp``, our function looks like:
+
+.. code-block:: C++
+
+    template <class T>
+    void getBpass(T* inbuffer, double* outbuffer, int nchans,
+                int nsamps) {
+    #pragma omp parallel for default(shared)
+        for (int jj = 0; jj < nchans; jj++) {
+            for (int ii = 0; ii < nsamps; ii++) {
+                outbuffer[jj] += inbuffer[(nchans * ii) + jj];
+            }
+        }
+    }
+
+This function receives a block of data and sums that block along the time axis.
+We use an optional C pre-processor directive to enable OpenMP threading.
+Realistically this call is not required here, but it is left here of a clear
+example of how to quicly multi-thread a system of loops.
+
+
+Reporting an issue
+------------------
+
+`Post an issue on the GitHub repository
+<https://github.com/FRBs/sigpyproc3/issues>`_. When you post an issue,
+please provide the details to reproduce the issue.
+
+
+Contributing code or documentation
+----------------------------------
+

docs/index.rst

@@ -52,13 +52,14 @@ new modules and extensions.
 
 .. toctree::
   :maxdepth: 2
-  :caption: Contents
+  :caption: Documentation
 
   install
   modules
+  dev
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Tutorials
+  :maxdepth: 2
+  :caption: Tutorials
 
-   tutorials/quickstart.ipynb
+  tutorials/quickstart.ipynb

docs/modules.rst

@@ -1,7 +1,15 @@
-sigpyproc
-=========
+API Reference
+=============
 
 .. toctree::
    :maxdepth: 4
 
-   sigpyproc
+   api/sigpyproc.Filterbank
+   api/sigpyproc.FoldedData
+   api/sigpyproc.FourierSeries
+   api/sigpyproc.Header
+   api/sigpyproc.HeaderParams
+   api/sigpyproc.Readers
+   api/sigpyproc.TimeSeries
+   api/sigpyproc.Utils
+   api/sigpyproc.libSigPyProc

environment_doc.yml

@@ -0,0 +1,11 @@
+name: sigpyproc_docs_env
+
+channels:
+  - conda-forge
+
+dependencies:
+  - python=3.7
+  - fftw
+  - numpy
+  - pip
+  - setuptools