Api (#48)

* WIP

* WIP

* WIP

* cleaned up multi

* WIP

* WIP

* WIP

* WIP

* WIP

* WIP

* WIP

* WIP

* split up python module

* WIP

* WIP

* WIP

* WIP

* WIP

* ok

* fixed bugs from rebase

* WIP

* fixed broken test

* WIP

* fixed python

* WIP

* sphinx help

* including new commands

* docs

* WIP

* WIP

* more tests

* added missing public header

* WIP

docs/CMakeLists.txt

@@ -0,0 +1,67 @@
+find_package(Doxygen)
+find_package(Sphinx)
+
+
+if (DOXYGEN_FOUND AND SPHINX_FOUND)
+
+    # #Utility to generate command line documentation
+    add_executable(gendoc src/gendoc.cpp)
+    target_link_libraries(gendoc PRIVATE
+      slsDetectorShared
+    )
+    set_target_properties(gendoc PROPERTIES 
+      RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin
+    )
+
+    
+    
+
+    #Doxygen
+    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+
+    #Sphinx
+    set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+    set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR})
+
+    set(SPHINX_SOURCE_FILES
+      src/commandline.rst
+      src/container_utils.rst
+      src/dependencies.rst
+      src/detector.rst
+      src/index.rst
+      src/installation.rst
+      src/pydetector.rst
+      src/pyenums.rst
+      src/pyexamples.rst
+      src/receiver.rst
+      src/result.rst
+      src/type_traits.rst
+      src/ToString.rst
+      
+    )
+
+    foreach(filename ${SPHINX_SOURCE_FILES})
+      configure_file(${CMAKE_CURRENT_SOURCE_DIR}/${filename} 
+                    "${SPHINX_BUILD}/${filename}")
+    endforeach(filename ${SPHINX_SOURCE_FILES})
+
+    configure_file(
+        "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
+        "${SPHINX_BUILD}/conf.py"
+        @ONLY)
+
+    add_custom_target(docs
+                    gendoc
+                    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+                    COMMAND ${SPHINX_EXECUTABLE} -a -b html
+                    -Dbreathe_projects.slsDetectorPackage=${CMAKE_CURRENT_BINARY_DIR}/xml
+                    -c "${SPHINX_BUILD}"
+                    ${SPHINX_BUILD}/src 
+                    ${SPHINX_BUILD}/html
+                    COMMENT "Generating documentation with Sphinx")
+
+else (DOXYGEN_FOUND AND SPHINX_FOUND)
+  message("Doxygen and Sphinx are needed to build documentation")
+endif (DOXYGEN_FOUND AND SPHINX_FOUND)

docs/conf.py.in

@@ -0,0 +1,62 @@
+# 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:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- 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('.'))
+sys.path.insert(0, os.path.abspath('../bin/'))
+#sys.path.insert(0, '/home/l_frojdh/sls/build/bin')
+#sys.path.insert(0, @CMAKE_CURRENT_BINARY_DIR@)
+print(sys.path)
+
+# -- Project information -----------------------------------------------------
+
+project = 'slsDetectorPackage'
+copyright = '2019, PSD Detector Group'
+author = 'PSD Detector Group'
+version = '@PROJECT_VERSION@'
+
+# -- 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 = ['breathe',
+              'sphinx_rtd_theme',
+              'sphinx.ext.autodoc',
+              'sphinx.ext.napoleon',
+             ]
+
+breathe_default_project = "slsDetectorPackage"
+napoleon_use_ivar = True
+
+
+# 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 = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- 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 = "sphinx_rtd_theme"
+
+# 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 = ['_static']

docs/src/ToString.rst

@@ -0,0 +1,6 @@
+ToString
+==============
+
+String conversion
+
+.. doxygenfile:: ToString.h

docs/src/commandline.rst

@@ -0,0 +1,16 @@
+Command line interface
+==============================================
+
+Usage
+-------------
+
+Commands can be uses either with sls_detector_get or sls_detector_put
+
+.. code-block::
+
+    sls_detector_get vrf
+
+Commands
+-----------
+
+.. include:: ../commands.rst

docs/src/container_utils.rst

@@ -0,0 +1,14 @@
+ContainerUtils
+==================
+
+Helper functions to handle standard container compliant 
+containers. Supports array, vector, sls::Result etc.
+
+While not a part of the public API we aim not to change this
+interface too much. However, we don't give the same strong
+guarantees as for Detector etc. 
+
+Any reoccurring container operation should probably be added to
+this file.  
+
+.. doxygenfile:: container_utils.h

docs/src/dependencies.rst

@@ -0,0 +1,53 @@
+Dependencies
+=========================
+
+While we value few dependencies some libraries are required in 
+order to not have to reinvent the wheel. Due to the state of package
+management in C++ we decided to bundle some of them with our source
+code. These are found in the libs/ directory. 
+
+-----------------------
+Core
+-----------------------
+To use the basic building blocks, meaning sls_detector_get/put and 
+the shared libraries these are needed: 
+
+ * Linux, preferably recent kernel (currently no cross platform support)
+ * CMake > 3.9 
+ * C++11 compatible compiler. (We test with gcc and clang)
+ * ZeroMQ version 4
+
+-----------------------
+GUI
+-----------------------
+
+The GUI is currently using Qt4 but watch out for an upgrade to 5. 
+
+ * Qt 4.8
+ * Qwt 6
+
+-----------------------
+Python bindings
+-----------------------
+
+ * Python > 3.6
+ * pybind11 (packaged in libs/)
+
+
+-----------------------
+Documentation
+-----------------------
+
+The documentation that you are reading now is built with 
+
+ * Doxygen (to extract C++ classes etc.)
+ * Breathe (Sphinx plugin to handle doxygen xml)
+ * Sphinx 
+
+-----------------------
+Packaged in libs/
+-----------------------
+
+ * catch2 (unit testing)
+ * rapidjson (streaming from receiver)
+ * pybind11 (python bindings)  

docs/src/detector.rst

@@ -0,0 +1,16 @@
+Detector
+==============================================
+
+The sls::Detector is the new public API to control 
+detectors from C++. This API is also used internally
+for the Python bindings and the command line interface. 
+If a receiver has been configured this is also controlled
+through this class.
+
+Most, if not all, functions are called in parallel
+and the return value is a thin std::vector wrapper 
+containing results from all modules. (Result<T>)
+
+.. doxygenclass:: sls::Detector
+   :members:
+   :undoc-members:

docs/src/gendoc.cpp

@@ -0,0 +1,56 @@
+/** 
+ * Utility program to generate input files for the command line 
+ * documentation. Uses the string returned from sls_detector_help cmd
+ * 
+ */
+#include <fstream>
+#include <iostream>
+#include <sstream>
+#include <string>
+#include <vector>
+
+
+#include "CmdProxy.h"
+#include "Detector.h"
+#include "sls_detector_defs.h"
+
+std::string replace_all(const std::string &src, const std::string &from,
+                        const std::string &to) {
+
+    std::string results;
+    std::string::const_iterator end = src.end();
+    std::string::const_iterator current = src.begin();
+    std::string::const_iterator next =
+        std::search(current, end, from.begin(), from.end());
+    while (next != end) {
+        results.append(current, next);
+        results.append(to);
+        current = next + from.size();
+        next = std::search(current, end, from.begin(), from.end());
+    }
+    results.append(current, next);
+    return results;
+}
+
+int main() {
+
+    std::cout << "Generating command line documentation!\n";
+
+    sls::CmdProxy<sls::Detector> proxy(nullptr);
+    auto commands = proxy.GetProxyCommands();
+
+    std::ofstream fs("commands.rst");
+    fs << ".. glossary::\n";
+
+    for (const auto &cmd : commands) {
+        std::ostringstream os;
+        proxy.Call(cmd, {}, -1, slsDetectorDefs::HELP_ACTION, os);
+
+        auto tmp = os.str().erase(0, cmd.size());
+        auto usage = tmp.substr(0, tmp.find_first_of('\n'));
+        tmp.erase(0, usage.size());
+        auto help = replace_all(tmp, "\n\t", "\n\t\t");
+        fs << '\t' << cmd << usage << help << "\n";
+    }
+
+}

docs/src/index.rst

@@ -0,0 +1,50 @@
+.. slsDetectorPackage documentation master file, created by
+   sphinx-quickstart on Mon Jul 29 17:38:15 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to slsDetectorPackage's documentation!
+==============================================
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Installation:
+
+    installation
+    dependencies
+   
+.. toctree::
+    :caption: C++ API
+    :maxdepth: 2
+
+    detector
+    result
+    receiver
+
+.. toctree::
+    :caption: Python API
+    :maxdepth: 2
+
+    pydetector
+    pyenums
+    pyexamples
+
+.. toctree::
+    :caption: Command line
+    :maxdepth: 2
+
+    commandline  
+
+.. toctree::
+    :caption: Developer
+
+    container_utils
+    type_traits
+    ToString
+
+.. Indices and tables
+.. ==================
+
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`

docs/src/installation.rst

@@ -0,0 +1,5 @@
+
+Installation
+==============================================
+
+get the source etc.

docs/src/pydetector.rst

@@ -0,0 +1,9 @@
+Detector
+=====================================================
+
+.. py:currentmodule:: sls_detector
+
+.. autoclass:: ExperimentalDetector
+    :members:  
+    :undoc-members:
+    :show-inheritance:

docs/src/pyenums.rst

@@ -0,0 +1,12 @@
+Enums
+===========
+
+These enums are defined in slsDetectorDefs in the C++ package and 
+exposed to Python through pybind11.
+
+.. py:currentmodule:: sls_detector
+
+.. autoclass:: runStatus
+    :members:  
+    :undoc-members:
+    :show-inheritance:

docs/src/pyexamples.rst

@@ -0,0 +1,143 @@
+Examples
+================
+
+Some short hints on how to use the detector
+
+------------------------
+Simple threshold scan
+------------------------
+
+Assuming you have set up your detector with exposure time, period, enabled
+file writing etc.
+
+.. code-block:: python
+ 
+    from sls_detector import Eiger
+
+    d = Eiger()
+    threshold = range(0, 2000, 200)
+    for th in threshold:
+        d.vthreshold = th
+        d.acquire()
+    
+
+If we want to control the shutter of for example, the big X-ray box we can add
+this line in our code. It then opens the shutter just before the measurement
+and closes is afterwards.
+    
+::
+
+    with xrf_shutter_open(box, 'Fe'):
+        for th in threshold:
+            d.vthreshold = th
+            d.acquire()
+        
+        
+-----------------------
+Reading temperatures
+-----------------------       
+
+::
+
+    d.temp
+    >>
+    temp_fpga     :  43.19°C,  51.83°C
+    temp_fpgaext  :  38.50°C,  38.50°C
+    temp_10ge     :  39.50°C,  39.50°C
+    temp_dcdc     :  42.50°C,  42.50°C
+    temp_sodl     :  39.50°C,  40.50°C
+    temp_sodr     :  39.50°C,  40.50°C
+    temp_fpgafl   :  40.87°C,  37.61°C
+    temp_fpgafr   :  34.51°C,  35.63°C
+    
+    d.temp.fpga
+    >> temp_fpga     :  40.84°C,  39.31°C
+    
+    t = d.temp.fpga[0]
+    t
+    >> 40.551
+    
+    t = d.temp.fpga[:]
+    t
+    >> [40.566, 39.128]
+
+
+-----------------------
+Non blocking acquire
+-----------------------
+
+There are mainly two ways to achieve a non blocking acquire when calling from the Python API. One is to manually start
+the detector and the second one is to launch the normal acquire from a different process. Depending on your measurement
+it might also be better to run the other task in a seperate process and use acq in the main thread.
+But lets start looking at the at the manual way:
+
+::
+
+    import time
+    from sls_detector import Eiger
+    d = Eiger()
+
+    n = 10
+    t = 1
+
+    d.exposure_time = t
+    d.n_frames = n
+    d.reset_frames_caught()
+
+    #Start the measurement
+    t0 = time.time()
+    d.start_receiver()
+    d.start_detector()
+
+    #Wait for the detector to be ready or do other important stuff
+    time.sleep(t*n)
+
+    #check if the detector is ready otherwise wait a bit longer
+    while d.status != 'idle':
+        time.sleep(0.1)
+
+    #Stop the receiver after we got the frames
+    #Detector is already idle so we don't need to stop it
+    d.stop_receiver()
+
+    lost = d.frames_caught - n
+    print(f'{n} frames of {t}s took {time.time()-t0:{.3}}s with {lost} frames lost ')
+
+    #Reset to not interfere with a potential next measurement
+    d.reset_frames_caught()
+
+Instead launching d.acq() from a different process is a bit easier since the control of receiver and detector
+is handled in the acq call. However, you need to join the process used otherwise a lot of zombie processes would
+hang around until the main process exits.
+
+::
+
+    import time
+    from multiprocessing import Process
+    from sls_detector import Eiger
+
+    def acquire():
+        """
+        Create a new Eiger object that still referes to the same actual detector
+        and same shared memory. Then launch acq.
+        """
+        detector = Eiger()
+        detector.acq()
+
+    #This is the detector we use throughout the session
+    d = Eiger()
+
+    #Process to run acquire
+    p = Process(target=acquire)
+
+    #Start the thread and short sleep to allow the acq to start
+    p.start()
+    time.sleep(0.01)
+
+    #Do some other work
+    while d.busy is True:
+        print(d.busy)
+        time.sleep(0.1)
+
+    #Join the process
+    p.join()

docs/src/receiver.rst

@@ -0,0 +1,6 @@
+Receiver
+==============================================
+
+.. doxygenclass:: slsReceiver
+   :members:
+..    :undoc-members:

docs/src/result.rst

@@ -0,0 +1,4 @@
+Result
+==============================================
+
+.. doxygenfile:: Result.h

docs/src/type_traits.rst

@@ -0,0 +1,7 @@
+TypeTraits
+==============
+
+Template meta functions in the same spirit as type_traits
+from the standard library.
+
+.. doxygenfile:: TypeTraits.h