Dev/doc/add ctb to doc (#1455)

* added numpy for patterngenerator

* treat warnings as errors

* fix warnings during docu build

* added power and ctb to documentation

.github/workflows/build_documentation.yml

@@ -64,7 +64,7 @@ jobs:
                 cache: 'pip'
             
             - name: Install Python Packages
-              run: pip install sphinx sphinx_rtd_theme breathe pyyaml jinja2
+              run: pip install sphinx sphinx_rtd_theme breathe pyyaml jinja2 numpy
                
 
             - name: Build Documentation

docs/CMakeLists.txt

@@ -36,6 +36,7 @@ set(SPHINX_SOURCE_FILES
   src/consuming.rst
   src/dependencies.rst
   src/detector.rst
+  src/pyctb.rst
   src/index.rst
   src/installation.rst
   src/pydetector.rst
@@ -72,6 +73,8 @@ set(SPHINX_SOURCE_FILES
   src/softwarearchitecture.rst
   src/configcommands.rst
   src/Versioning.rst
+  src/Testing.rst
+  src/pypower.rst 
 )
 
 foreach(filename ${SPHINX_SOURCE_FILES})
@@ -105,7 +108,7 @@ add_custom_target(docs
               gendoc
               COMMAND python gen_server_doc.py
               COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
-              COMMAND ${SPHINX_EXECUTABLE} -a -b html
+              COMMAND ${SPHINX_EXECUTABLE} -W -a -b html
               -Dbreathe_projects.slsDetectorPackage=${CMAKE_CURRENT_BINARY_DIR}/xml
               -c "${SPHINX_BUILD}"
               ${SPHINX_BUILD}/src 
@@ -113,7 +116,7 @@ add_custom_target(docs
               COMMENT "Generating documentation with Sphinx")
 
 add_custom_target(rst
-              COMMAND ${SPHINX_EXECUTABLE} -a -b html
+              COMMAND ${SPHINX_EXECUTABLE} -W -a -b html
               -Dbreathe_projects.slsDetectorPackage=${CMAKE_CURRENT_BINARY_DIR}/xml
               -c "${SPHINX_BUILD}"
               ${SPHINX_BUILD}/src 

docs/conf.py.in

@@ -48,6 +48,8 @@ templates_path = ['_templates']
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+suppress_warnings = ["duplicate_declaration.cpp",]
+
 
 # -- Options for HTML output -------------------------------------------------
 

docs/src/Testing.rst

@@ -67,12 +67,14 @@ This runs all tests marked with the tag ``[.detectorintegration]`` for all detec
 If you want to run them for a specific virtual detector or a specific test use the following command:
 
 .. code-block:: console
+
     cd build
     python bin/test_simulators.py --servers jungfrau --test "[dacs]"
 
 You can exclude specific tests by adding the option ``~[<disable_test_name>]``. Again, we assume that this marker is added to the tests that you want to exclude. 
 
 .. code-block:: console
+
     cd build
     python bin/test_simulators.py --servers eiger jungfrau moench --test "[detectorintegration]~[disable_check_data_file]"
 
@@ -98,6 +100,7 @@ If a test requires a detector mark them with the pytest marker ``@pytest.mark.de
 To run only tests requiring virtual detectors use the following command:
 
 .. code-block:: console
+    
     #in build
     python -m pytest -m detectorintegration ../python/tests/
 

docs/src/dependencies.rst

@@ -53,9 +53,9 @@ To build the python module the following dependencies are needed:
 
     Refer :ref:`pybind11 notes. <pybind for different slsDetectorPackage versions>`  
 
--------------------------------
+------------------------------------
 Dependencies to build documentation
--------------------------------
+------------------------------------
 
 To build this documentation that you are reading now the following dependencies are needed: 
 
@@ -76,7 +76,7 @@ To build the GUI the following dependencies are needed:
 
     Qwt is bundled in libs. One does not need to pre-install it on the system.
 
-------------------------------------------------------
+-----------------------------------------------------
 Dependencies to build Moench and Jungfrau executables
 -----------------------------------------------------
 

docs/src/gendoc.cpp

@@ -45,13 +45,16 @@ int main() {
 
     for (const auto &cmd : commands) {
         std::ostringstream os;
-        std::cout << cmd << '\n';
         caller.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| ");
+
+        if (help.back() != '\n') {
+            help.push_back('\n');
+        }
         fs << '\t' << cmd << usage << help << "\n";
     }
 

docs/src/index.rst

@@ -48,7 +48,9 @@ slsDetectorPackage
 
     pygettingstarted
     pydetector
+    pyctb
     pyenums
+    pypower
     pyexamples
     pyPatternGenerator
     pattern

docs/src/pyctb.rst

@@ -0,0 +1,15 @@
+Ctb
+=====================================================
+
+.. py:currentmodule:: slsdet
+
+.. autoclass:: Ctb
+    :members:  
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+
+
+
+

docs/src/pypower.rst

@@ -0,0 +1,12 @@
+Power Supply
+===============
+
+Helper class to control power supplies on the Chip Test Board (CTB, Xilinx CTB). 
+
+.. py:currentmodule:: slsdet
+
+.. autoclass:: Power
+    :members:  
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:

python/slsdet/ctb.py

@@ -27,10 +27,34 @@ class Ctb(Detector):
 
     @property
     def powers(self):
+        """ 
+        [Chiptestboard][Xilinx CTB] Power names and values of all power supplies.
+
+        Example
+        -----------
+        >>> # print all powers with DAC and info if enabled
+        >>> d.powers 
+        >>> # set DAC or enables for power supply VA 
+        >>> d.powers.VA = 1200
+        >>> # enable or disable power subbly VA
+        >>> d.powers.VA.enable()
+        >>> d.powers.VA.disable()
+        >>> # get dac value of power supply VA
+        >>> d.powers.VA.dac
+        >>> # check if power supply VA is enabled
+        >>> d.powers.VA.enabled
+        >>> # print both enabled and dac value of power supply VA
+        >>> d.powers.VA
+        """
         return self._powers
     
     @property
     def powerlist(self):
+        """
+        List of power supply names on the Chip Test Board.
+
+        :setter: List of custom power supply names to set. 
+        """
         return self.getPowerNames()
 
     @powerlist.setter

python/slsdet/detector.py

@@ -833,10 +833,10 @@ class Detector(CppDetectorApi):
         Note
         ----
         Sets up the following for every module:\n
-        \t\t[Eiger] txdelay_left to (2 * mod_index * n_delay), \n
-        \t\t[Eiger] txdelay_right to ((2 * mod_index + 1) * n_delay) and \n
-        \t\t[Eiger] txdelay_frame to (2 *num_modules * n_delay)  \n
-        \t\t[Jungfrau][Moench][Mythen3] txdelay_frame to (num_modules * n_delay)\n\n
+        \t\t[Eiger] txdelay_left to (2 \* mod_index \* n_delay), \n
+        \t\t[Eiger] txdelay_right to ((2 \* mod_index + 1) \* n_delay) and \n
+        \t\t[Eiger] txdelay_frame to (2 \* num_modules \* n_delay)  \n
+        \t\t[Jungfrau][Moench][Mythen3] txdelay_frame to (num_modules \* n_delay)\n\n
         Please refer txdelay_left, txdelay_right and txdelay_frame for details.
         """
         return self.getTransmissionDelay()
@@ -1313,10 +1313,10 @@ class Detector(CppDetectorApi):
     @property
     def zmqhwm(self):
         """
-        Client's zmq receive high water mark. Default is the zmq library's default (1000), can also be set here using -1. 
-        This is a high number and can be set to 2 for gui purposes. 
+        Client's zmq receive high water mark. Default is the zmq library's default (1000), can also be set here using -1.
+        This is a high number and can be set to 2 for gui purposes.
         One must also set the receiver's send high water mark to similar value. Final effect is sum of them.
-	    Setting it via command line is useful only before zmq enabled (before opening gui).
+        Setting it via command line is useful only before zmq enabled (before opening gui).
         """
         return self.getClientZmqHwm()
 
@@ -2312,13 +2312,16 @@ class Detector(CppDetectorApi):
     @property
     @element
     def threshold(self):
-        """[Eiger][Mythen3] Threshold in eV
+        """
+        [Eiger][Mythen3] Threshold in eV
         
         Note
         ----
-        To change settings as well or set threshold without trimbits, use setThresholdEnergy.
+        To change settings as well or set threshold without trimbits, 
+        use setThresholdEnergy.
 
-        :setter: It loads trim files from settingspath.\n [Mythen3] An energy of -1 will pick up values from detector.
+        :setter: It loads trim files from settingspath.\n 
+            [Mythen3] An energy of -1 will pick up values from detector.
         """
         
         if self.type == detectorType.MYTHEN3:

slsDetectorSoftware/src/CallerSpecial.cpp

@@ -1586,7 +1586,7 @@ std::string Caller::define_bit(int action) {
 std::string Caller::definelist_reg(int action) {
     std::ostringstream os;
     if (action == defs::HELP_ACTION) {
-        os << "List of user-defined register definitions in shared memory."
+        os << "\n\t List of user-defined register definitions in shared memory."
            << '\n';
     } else if (action == defs::PUT_ACTION) {
         throw RuntimeError("cannot put");
@@ -1605,7 +1605,8 @@ std::string Caller::definelist_reg(int action) {
 std::string Caller::definelist_bit(int action) {
     std::ostringstream os;
     if (action == defs::HELP_ACTION) {
-        os << "List of user-defined bit definitions in shared memory." << '\n';
+        os << "\n\t List of user-defined bit definitions in shared memory."
+           << '\n';
     } else if (action == defs::PUT_ACTION) {
         throw RuntimeError("cannot put");
     } else if (action == defs::GET_ACTION) {