WIP

docs/CMakeLists.txt

@@ -42,6 +42,7 @@ if (DOXYGEN_FOUND AND SPHINX_FOUND)
       src/result.rst
       src/type_traits.rst
       src/ToString.rst
+      src/examples.rst
       
     )
 

docs/src/consuming.rst

@@ -3,16 +3,18 @@ Consuming slsDetectorPackage
 
 Depending on how you want to build your integration with 
 slsDetectorPackage there are a few different ways to 
-consume the package. 
+consume our package. The recommended way is to use one of the 
+CMake approaches. 
 
 
 
-CMake with submodule in your project
+CMake: slsDetectorPackage as submodule in your project
 ---------------------------------------
 
 If you are using CMake to build your integration and want to build everything
-in one go we support adding slsDetectorPackage as a subfolder in your cmake project. 
-a minimal example would be. 
+in one go, we support adding slsDetectorPackage as a subfolder in your cmake project. 
+
+A minimal CMakeLists.txt could look like this: 
 
 .. code-block:: cmake
 
@@ -27,15 +29,46 @@ a minimal example would be.
     #Link towards slsDetectorShared
     target_link_libraries(example slsDetectorShared)
 
-An example that also uses git submodules is available in our github repo
+A fully working example can be found at:
 
 https://github.com/slsdetectorgroup/cmake-subfolder-example
 
 
+CMake: find_package(slsDetectorPackage)
+------------------------------------------
+
+If you have compiled and installed slsDetectorPackage we also support
+find_package in CMake. If installed in a system wide location no path
+should be needed, otherwise specify cmake prefix path. 
+
+.. code-block:: cmake 
+
+    cmake_minimum_required(VERSION 3.12)
+    project(myintegration)
+
+    find_package(slsDetectorPackage 5.0 REQUIRED)
+    add_executable(example main.cpp)
+    target_link_libraries(example slsDetectorShared)
+
+
+Then assuming the slsDetectorPackage is installed in /path/to/sls/install
+you should be able to configure and build your project in this way. 
+
+.. code-block:: bash
+
+    cmake ../path/to/your/source -DCMAKE_PREFIX_PATH=/path/to/sls/install
+    make
+
+
+A minimal example is available at: https://github.com/slsdetectorgroup/minimal-cmake
+
 No tools minimal approach
 -----------------------------
 
-.. code-block:: c++
+While not recommended it is still possible to specify the include and library paths
+manually when invoking g++. This can sometimes be handy for a quick try. 
+
+.. code-block:: cpp
 
     #include "Detector.h"
     #include <iostream>
@@ -54,7 +87,8 @@ No tools minimal approach
         auto mac = det.getSourceUDPMAC()[module];
         std::cout << "Mac addr of module "<< module <<  " is " <<  mac.str() << '\n'; 
 
-    }⏎       
+    }     
+
 
 .. code-block:: bash
 

docs/src/dependencies.rst

@@ -13,7 +13,7 @@ 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 
+ * CMake > 3.12 
  * C++11 compatible compiler. (We test with gcc and clang)
  * ZeroMQ version 4
 
@@ -24,7 +24,7 @@ GUI
 The GUI is currently using Qt4 but watch out for an upgrade to 5. 
 
  * Qt 4.8
- * Qwt 6
+ * Qwt 6.1
 
 -----------------------
 Python bindings

docs/src/examples.rst

@@ -0,0 +1,115 @@
+
+
+
+Examples
+===========
+
+Setup 
+------------
+
+The examples here assume that you have compiled and installed slsDetectorPackage
+to ~/sls/install and that the option for SLS_USE_SIMULATOR was enabled. This also builds
+the virtual detector servers that we will be using for testing. 
+
+We also add ~/sls/detector/install/bin to the path for convenience. 
+
+Compile examples
+-------------------
+
+The source code of the examples is available at:
+https://github.com/slsdetectorgroup/api-examples
+
+
+.. code-block:: bash
+
+    git clone https://github.com/slsdetectorgroup/api-examples.git
+    mkdir build && cd build
+    cmake ../api-examples -DCMAKE_PREFIX_PATH=~/sls/detector/install
+    make
+
+Below follows a short description of what is included in the examples.
+
+
+Running a config file [e1]
+-----------------------------
+
+
+.. code-block:: cpp
+
+    #include "Detector.h"
+    ...
+    sls::Detector det;
+    det.loadConfig("path/to/config/file.config");
+
+
+
+To configure the connection between PC and detector the easiest 
+is to run a config file. For this example we first launch a virtual Jungfrau server and
+then set up the detector. 
+
+**Launch a virtual detector server**
+
+.. code-block:: bash
+
+    jungfrauDetectorServer_virtual
+
+This launches a virtual Jungfrau detector server. As default is uses port 1952 and 1953
+for communication over TCP. Most commands go on 1952 and only stop and status on 1953. 
+
+**Run example to configure**
+
+.. code-block:: bash
+
+    ./e1-config one_det_no_receiver.config
+    - 12:01:06.371 INFO: Shared memory deleted /slsDetectorPackage_multi_0_sls_0
+    - 12:01:06.371 INFO: Shared memory deleted /slsDetectorPackage_multi_0
+    - 12:01:06.372 INFO: Shared memory created /slsDetectorPackage_multi_0
+    - 12:01:06.376 INFO: Loading configuration file: one_det_no_receiver.config
+    - 12:01:06.376 INFO: Adding detector localhost
+    - 12:01:06.377 INFO: Shared memory created /slsDetectorPackage_multi_0_sls_0
+    - 12:01:06.377 INFO: Checking Detector Version Compatibility
+    - 12:01:06.378 INFO: Detector connecting - updating!
+    hostname [localhost]
+
+
+    Jungfrau detector with 1 modules configured
+
+
+Using the return type sls::Result [e2]
+-----------------------------------------
+
+Since many our detectors have multiple modules we cannot return
+a single value when reading from the Detector. Hostname, Ip and also
+for example exposure time can differ between modules. 
+
+Therefore we return Result<T> which is a thin wrapper around
+std::vector. 
+
+.. code-block:: cpp
+
+    sls::Result<int> res1{1, 1, 1};
+    std::cout << "res1: " << res1 << '\n';
+    res1.squash();
+    res1.squash(-1);
+
+
+
+Setting exposure time [e3]
+-----------------------------------------
+
+For setting times, like exposure time, period, delay etc. 
+we use std::chrono::duration. 
+
+Example 3 shows how to set and read exposure time as well
+as converting to floating point. 
+
+.. code-block:: cpp
+
+    #include "Detector.h"
+    #include <chrono>
+    ...
+    std::chrono::microseconds t0{500};
+    det.setExptime(t0);
+
+
+

docs/src/index.rst

@@ -6,6 +6,11 @@
 Welcome to slsDetectorPackage's documentation!
 ==============================================
 
+.. note :: 
+
+    This is the documentation for the latest development version of slsDetectorPackage
+    For documentation on current and previous releases visit the official page: https://www.psi.ch/en/detectors/documentation
+
 .. toctree::
     :maxdepth: 1
     :caption: Installation:
@@ -21,6 +26,7 @@ Welcome to slsDetectorPackage's documentation!
     detector
     result
     receiver
+    examples
 
 .. toctree::
     :caption: Python API

docs/src/installation.rst

@@ -2,4 +2,24 @@
 Installation
 ==============================================
 
-get the source etc.
+Build from source using CMake
+---------------------------------
+
+.. note :: 
+
+    The default branch of our git repository is developer. It contains the 
+    latest development version. It is expected to compile and work but 
+    features might be added or tweaked. In some cases the API might also change
+    without being communicated. If absolute stability of the API is needed please
+    use one of the release versions. 
+
+.. code-block:: bash
+
+    git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git
+    mkdir build && cd build
+    cmake ../slsDetectorPackage -DCMAKE_INSTALL_PREFIX=/your/install/path
+    make -j12
+    make install
+
+    
+

docs/src/pydetector.rst

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

slsDetectorServers/jungfrauDetectorServer/CMakeLists.txt

@@ -14,15 +14,12 @@ add_executable(jungfrauDetectorServer_virtual
     ../slsDetectorServer/src/communication_funcs_UDP.c    
 )
 
-include_directories(
+target_include_directories(jungfrauDetectorServer_virtual
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}
     ../slsDetectorServer/include
     ../../slsSupportLib/include
 )
 
-target_include_directories(jungfrauDetectorServer_virtual
-    PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}
-)
-
 target_compile_definitions(jungfrauDetectorServer_virtual
     PUBLIC JUNGFRAUD VIRTUAL STOP_SERVER
 )
@@ -36,5 +33,6 @@ set_target_properties(jungfrauDetectorServer_virtual PROPERTIES
 )
 
 install(TARGETS jungfrauDetectorServer_virtual
-    RUNTIME  DESTINATION ${CMAKE_INSTALL_BINDIR}
+    EXPORT "${TARGETS_EXPORT_NAME}"
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 )