improved documentation

docs/CMakeLists.txt

@@ -12,6 +12,8 @@ set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR})
 
 set(SPHINX_SOURCE_FILES
   src/index.rst
+  src/Installation.rst
+  src/Requirements.rst
   src/NDArray.rst
   src/NDView.rst
   src/File.rst
@@ -26,6 +28,7 @@ set(SPHINX_SOURCE_FILES
   src/pyVarClusterFinder.rst
   src/pyFile.rst
   src/pyCtbRawFile.rst
+  src/pyRawFile.rst
   src/pyRawMasterFile.rst
 )
 

docs/src/Installation.rst

@@ -0,0 +1,101 @@
+Installation
+===============
+
+conda/mamaba
+~~~~~~~~~~~~~~~~
+
+.. note ::
+
+    aare is developing rapidly. Check for the latest release by 
+    using: **conda search aare -c slsdetectorgroup**
+
+
+.. code-block:: bash
+
+    # Install a specific version: 
+    conda install aare=2024.11.11.dev0 -c slsdetectorgroup
+
+
+cmake (development install)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    git clone git@github.com:slsdetectorgroup/aare.git --branch=v1 #or using http...
+    mkdir build
+    cd build
+
+    #configure using cmake
+    cmake ../aare
+
+    #build (replace 4 with the number of threads you want to use)
+    make -j4 
+
+
+    # add the build folder to your PYTHONPATH
+
+cmake install and use in your C++ project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    #build and install aare 
+    git clone git@github.com:slsdetectorgroup/aare.git --branch=v1 #or using http...
+    mkdir build
+    cd build
+
+    #configure using cmake
+    cmake ../aare -DCMAKE_INSTALL_PREFIX=/where/to/put/aare
+
+    #build (replace 4 with the number of threads you want to use)
+    make -j4 
+
+    #install
+    make install
+
+
+    #Now configure your project
+    cmake .. -DCMAKE_PREFIX_PATH=SOME_PATH
+
+
+cmake options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For detailed options see the CMakeLists.txt file in the root directory of the project.
+
+.. code-block:: bash
+
+    # usage (or edit with ccmake .)
+    cmake ../aare -DOPTION1=ON -DOPTION2=OFF
+
+
+**AARE_SYSTEM_LIBRARIES "Use system libraries" OFF**
+
+Use system libraries instead of using FetchContent to pull in dependencies. Default option is off.
+
+
+**AARE_PYTHON_BINDINGS "Build python bindings" ON**
+
+Build the Python bindings. Default option is on. 
+
+.. warning ::
+
+    If you have a newer system Python compared to the one in your virtual environment,
+    you might have to pass -DPython_FIND_VIRTUALENV=ONLY to cmake.
+
+**AARE_TESTS "Build tests" OFF**
+
+Build unit tests. Default option is off.
+
+**AARE_EXAMPLES "Build examples" OFF**
+
+**AARE_DOCS "Build documentation" OFF**
+
+Build documentation. Needs doxygen, sphinx and breathe. Default option is off.
+Requires a separate make docs.
+
+**AARE_VERBOSE "Verbose output" OFF**
+
+**AARE_CUSTOM_ASSERT "Use custom assert" OFF**
+
+Enable custom assert macro to check for errors. Default option is off.

docs/src/Requirements.rst

@@ -0,0 +1,23 @@
+Requirements
+==============================================
+
+- C++17 compiler (gcc 8/clang 7)
+- CMake 3.14+
+
+**Internally used libraries**
+
+.. note ::
+
+    These can also be picked up from the system/conda environment by specifying:
+    -DAARE_SYSTEM_LIBRARIES=ON during the cmake configuration.
+
+- pybind11
+- fmt
+- nlohmann_json
+- ZeroMQ
+
+**Extra dependencies for building documentation**
+
+- Sphinx
+- Breathe
+- Doxygen

docs/src/index.rst

@@ -5,12 +5,22 @@ AARE
 
     Hello
 
+
+.. toctree::
+    :caption: Installation
+    :maxdepth: 1
+    
+    Installation
+    Requirements
+
+
 .. toctree::
     :caption: Python API
     :maxdepth: 1
     
     pyFile
     pyCtbRawFile
+    pyRawFile
     pyRawMasterFile
     pyVarClusterFinder
 

docs/src/pyRawFile.rst

@@ -0,0 +1,10 @@
+RawFile
+===================
+
+.. py:currentmodule:: aare
+
+.. autoclass:: RawFile
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:

python/src/raw_file.hpp

@@ -23,63 +23,67 @@ using namespace ::aare;
 void define_raw_file_io_bindings(py::module &m) {
     py::class_<RawFile>(m, "RawFile")
         .def(py::init<const std::filesystem::path &>())
-        .def("read_frame", [](RawFile &self) {
+        .def("read_frame",
-            size_t image_size = self.bytes_per_frame();
+             [](RawFile &self) {
-            py::array image;
+                 size_t image_size = self.bytes_per_frame();
-            std::vector<ssize_t> shape;
+                 py::array image;
-            shape.reserve(2);
+                 std::vector<ssize_t> shape;
-            shape.push_back(self.rows());
+                 shape.reserve(2);
-            shape.push_back(self.cols());
+                 shape.push_back(self.rows());
+                 shape.push_back(self.cols());
 
-            // return headers from all subfiles
+                 // return headers from all subfiles
-            py::array_t<DetectorHeader> header(self.n_mod());
+                 py::array_t<DetectorHeader> header(self.n_mod());
 
-            const uint8_t item_size = self.bytes_per_pixel();
+                 const uint8_t item_size = self.bytes_per_pixel();
-            if (item_size == 1) {
+                 if (item_size == 1) {
-                image = py::array_t<uint8_t>(shape);
+                     image = py::array_t<uint8_t>(shape);
-            } else if (item_size == 2) {
+                 } else if (item_size == 2) {
-                image = py::array_t<uint16_t>(shape);
+                     image = py::array_t<uint16_t>(shape);
-            } else if (item_size == 4) {
+                 } else if (item_size == 4) {
-                image = py::array_t<uint32_t>(shape);
+                     image = py::array_t<uint32_t>(shape);
-            }
+                 }
-            self.read_into(reinterpret_cast<std::byte *>(image.mutable_data()),
+                 self.read_into(
-                           header.mutable_data());
+                     reinterpret_cast<std::byte *>(image.mutable_data()),
+                     header.mutable_data());
 
-            return py::make_tuple(header, image);
+                 return py::make_tuple(header, image);
-        })
+             })
-        .def("read_n", [](RawFile &self, size_t n_frames) {
+        .def("read_n",
-            py::array image;
+             [](RawFile &self, size_t n_frames) {
-            std::vector<ssize_t> shape;
+                 py::array image;
-            shape.reserve(3);
+                 std::vector<ssize_t> shape;
-            shape.push_back(n_frames);
+                 shape.reserve(3);
-            shape.push_back(self.rows());
+                 shape.push_back(n_frames);
-            shape.push_back(self.cols());
+                 shape.push_back(self.rows());
-            
+                 shape.push_back(self.cols());
-            // return headers from all subfiles
-            py::array_t<DetectorHeader> header({self.n_mod(),n_frames});
 
-            const uint8_t item_size = self.bytes_per_pixel();
+                 // return headers from all subfiles
-            if (item_size == 1) {
+                 py::array_t<DetectorHeader> header({self.n_mod(), n_frames});
-                image = py::array_t<uint8_t>(shape);
-            } else if (item_size == 2) {
-                image = py::array_t<uint16_t>(shape);
-            } else if (item_size == 4) {
-                image = py::array_t<uint32_t>(shape);
-            }
-            self.read_into(reinterpret_cast<std::byte *>(image.mutable_data()),n_frames,
-                           header.mutable_data());
 
-            return py::make_tuple(header, image);
+                 const uint8_t item_size = self.bytes_per_pixel();
+                 if (item_size == 1) {
+                     image = py::array_t<uint8_t>(shape);
+                 } else if (item_size == 2) {
+                     image = py::array_t<uint16_t>(shape);
+                 } else if (item_size == 4) {
+                     image = py::array_t<uint32_t>(shape);
+                 }
+                 self.read_into(
+                     reinterpret_cast<std::byte *>(image.mutable_data()),
+                     n_frames, header.mutable_data());
 
-        })
+                 return py::make_tuple(header, image);
+             })
         .def("frame_number", &RawFile::frame_number)
         .def_property_readonly("bytes_per_frame", &RawFile::bytes_per_frame)
         .def_property_readonly("pixels_per_frame", &RawFile::pixels_per_frame)
         .def_property_readonly("bytes_per_pixel", &RawFile::bytes_per_pixel)
         .def("seek", &RawFile::seek, R"(
-            Seek to a specific frame number.
+            Seek to a frame index in file.
             )")
-        .def("tell", &RawFile::tell)
+        .def("tell", &RawFile::tell, R"(
+            Return the current frame number.)")
         .def_property_readonly("total_frames", &RawFile::total_frames)
         .def_property_readonly("rows", &RawFile::rows)
         .def_property_readonly("cols", &RawFile::cols)
@@ -88,6 +92,4 @@ void define_raw_file_io_bindings(py::module &m) {
         .def_property_readonly("n_mod", &RawFile::n_mod)
         .def_property_readonly("detector_type", &RawFile::detector_type)
         .def_property_readonly("master", &RawFile::master);
-        
-        
 }

python/src/raw_master_file.hpp

@@ -22,9 +22,23 @@ namespace py = pybind11;
 using namespace ::aare;
 
 void define_raw_master_file_bindings(py::module &m) {
-py::class_<RawMasterFile>(m, "RawMasterFile")
+    py::class_<RawMasterFile>(m, "RawMasterFile")
         .def(py::init<const std::filesystem::path &>())
-        .def("data_fname", &RawMasterFile::data_fname)
+        .def("data_fname", &RawMasterFile::data_fname, R"(
+
+            Parameters
+            ------------
+                module_index : int 
+                        module index (d0, d1 .. dN)
+                file_index : int 
+                        file index (f0, f1 .. fN)
+
+            Returns
+            ----------
+                os.PathLike
+                        The name of the data file.
+
+            )")
         .def_property_readonly("version", &RawMasterFile::version)
         .def_property_readonly("detector_type", &RawMasterFile::detector_type)
         .def_property_readonly("timing_mode", &RawMasterFile::timing_mode)
@@ -43,9 +57,23 @@ py::class_<RawMasterFile>(m, "RawMasterFile")
         .def_property_readonly("total_frames_expected",
                                &RawMasterFile::total_frames_expected)
         .def_property_readonly("geometry", &RawMasterFile::geometry)
-        .def_property_readonly("analog_samples", &RawMasterFile::analog_samples)
+        .def_property_readonly("analog_samples", &RawMasterFile::analog_samples, R"(
+            Number of analog samples
+
+            Returns
+            ----------
+                int | None
+                    The number of analog samples in the file (or None if not enabled)
+            )")
         .def_property_readonly("digital_samples",
-                               &RawMasterFile::digital_samples)
+                               &RawMasterFile::digital_samples,  R"(
+            Number of digital samples
+
+            Returns
+            ----------
+                int | None
+                    The number of digital samples in the file (or None if not enabled)
+            )")
 
         .def_property_readonly("transceiver_samples",
                                &RawMasterFile::transceiver_samples)
@@ -54,5 +82,4 @@ py::class_<RawMasterFile>(m, "RawMasterFile")
         .def_property_readonly("scan_parameters",
                                &RawMasterFile::scan_parameters)
         .def_property_readonly("roi", &RawMasterFile::roi);
-
 }