[WIP] Integrating Doxygen/Breathe with TECA's rtd

.gitignore

@@ -1,4 +1,7 @@
 *.sw[a-z]
 *.patch
 _build
+html
+xml
 *.pt
+.DS_store

alg/teca_2d_component_area.h

@@ -44,6 +44,22 @@ stored in the output dataset metadata in the following keys:
     background_id - the label used for cells outside of the segmentation,
                     i.e. the background. This can be used to skip processing
                     of the background when desirable.
+
+@rst
+.. table:: Algorithm Properties
+
+    +----------------------------+------------------------------------------------------------+
+    |         Property           |                      Description                           |
+    +============================+============================================================+
+    | component_variable         | the component variable name containing the region labels.  |
+    +----------------------------+------------------------------------------------------------+
+    | contiguous_component_ids   | the label used for cells inside the segmentation.          |
+    +----------------------------+------------------------------------------------------------+
+    | background_id              | | the label used for cells outside of the segmentation,    |
+    |                            | | i.e. the background. This can be used to skip processing |
+    |                            | | of the background when desirable.                        |
+    +----------------------------+------------------------------------------------------------+
+@endrst
 */
 class teca_2d_component_area : public teca_algorithm
 {
@@ -57,18 +73,23 @@ class teca_2d_component_area : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the name of the input array
+    // The component variable name containing the region labels.
     TECA_ALGORITHM_PROPERTY(std::string, component_variable)
 
-    // set this only if you know for certain that label ids are contiguous and
-    // start at 0. this enables use of a faster implementation.
+    /** @fn set_contiguous_component_ids
+     *  @attention set this only if you know for certain that label ids
+     *             are contiguous and start at 0. this enables use of a
+     *             faster implementation.
+     */
     TECA_ALGORITHM_PROPERTY(int, contiguous_component_ids)
-
-    // set this to override the component label used for background. By default
-    // this is set to -1 to indicate that the value should be obtained from the
-    // metadata key `background_id`.  Note that TECA's connected component
-    // labeler uses the id 0 for the background and passes this in a metadata
-    // key and as a result no action is required.
+
+    /** @fn set_background_id
+     *  @note By default this is set to -1 to indicate that the value should
+     *        be obtained from the metadata key `background_id`.
+     *        TECA's connected component labeler uses the id 0 for the
+     *        background and passes this in a metadata key and as a result
+     *        no action is required.
+     */
     TECA_ALGORITHM_PROPERTY(long, background_id)
 
 protected:

alg/teca_bayesian_ar_detect.h

@@ -49,28 +49,53 @@ class teca_bayesian_ar_detect : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the name of the input array
+    /** @anchor ivt_variable
+     * @name ivt_variable
+     * Set the name of the input array
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, ivt_variable)
 
-    // set the names of columns in the parameter table.
+    /** @anchor min_ivt_variable
+     * @name min_ivt_variable
+     * Set the name of the min IVT column in the parameter table.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, min_ivt_variable)
+    ///@}
+
+    /** @anchor min_component_area_variable
+     * @name min_component_area_variable
+     * Set the name of the component area column in the parameter table.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, min_component_area_variable)
+    ///@}
+
+    /** @anchor hwhm_latitude_variable
+     * @name hwhm_latitude_variable
+     * Set the name of the HWHM lattitude column in the parameter table.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, hwhm_latitude_variable)
+    ///@}
 
-    // flag indicating verbose terminal output is desired.
-    // default is 0
     TECA_ALGORITHM_PROPERTY(int, verbose)
 
-    // set/get the number of threads in the pool. setting
-    // to -1 results in a thread per core factoring in all MPI
-    // ranks running on the node. the default is -1.
+    /** set the number of threads in the pool. setting
+     *  to -1 results in a thread per core factoring in all MPI
+     *  ranks running on the node. the default is -1.
+     */
     void set_thread_pool_size(int n_threads);
+
+    /** get the number of threads in the pool. the default is -1. */
     unsigned int get_thread_pool_size() const noexcept;
 
-    // override the input connections because we are going to
-    // take the first input and use it to generate metadata.
-    // the second input then becomes the only one the pipeline
-    // knows about.
+    /** override the input connections because we are going to
+     *  take the first input and use it to generate metadata.
+     *  the second input then becomes the only one the pipeline
+     *  knows about.
+     */
     void set_input_connection(unsigned int id,
         const teca_algorithm_output_port &port) override;
 

alg/teca_binary_segmentation.h

@@ -30,24 +30,65 @@ class teca_binary_segmentation : public teca_algorithm
     TECA_ALGORITHM_CLASS_NAME(teca_binary_segmentation)
     ~teca_binary_segmentation();
 
-    // set the name of the output array to store the resulting segmentation in
+    /** @anchor segmentation_variable
+     * @name segmentation_variable
+     * Set the name of the output array to store the resulting segmentation in.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, segmentation_variable)
+    ///@}
 
     // set extra metadata for the segmentation variable
+    /** @anchor segmentation_variable_attributes
+     * @name segmentation_variable_attributes
+     * Set extra metadata for the segmentation variable.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(teca_metadata, segmentation_variable_attributes)
+    ///@}
 
-    // set the name of the input array to segment
+    /** @anchor threshold_variable
+     * @name threshold_variable
+     * Set the name of the input array to segment.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, threshold_variable)
+    ///@}
 
-    // Set the threshold range. The defaults are (-infinity, infinity].
+    /** @anchor low_threshold_value
+     * @name low_threshold_value
+     * Sets the low threshold value. default is -infinity.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, low_threshold_value)
+    ///@}
+    /** @anchor high_threshold_value
+     * @name high_threshold_value
+     * Sets the high threshold value. default is infinity.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, high_threshold_value)
-
-    // Set the threshold mode. In BY_PERCENTILE mode low and high thresholds
-    // define the percentiles (0 to 100) between which data is in the
-    // segmentation. default is BY_VALUE.
-    enum {BY_VALUE=0, BY_PERCENTILE=1};
+    ///@}
+
+    /** list threshold modes. In BY_PERCENTILE mode low and high thresholds
+     *  define the percentiles (0 to 100) between which data is in the
+     *  segmentation.
+     */
+    enum
+    {
+        /** 0 */
+        BY_VALUE=0,
+        /** 1 */
+        BY_PERCENTILE=1
+    };
+
+    /** @anchor threshold_mode
+     * @name threshold_mode
+     * Set the threshold mode. default is BY_VALUE
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(int, threshold_mode);
+    ///@}
 
     void set_threshold_by_percentile() { set_threshold_mode(BY_PERCENTILE); }
     void set_threshold_by_value() { set_threshold_mode(BY_VALUE); }

alg/teca_cartesian_mesh_regrid.h

@@ -37,21 +37,45 @@ class teca_cartesian_mesh_regrid : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the list of arrays to move from the source
-    // to the target
+    /** @anchor arrays
+     * @name arrays
+     * Set the list of arrays to move from the source to the target.
+     */
+    ///@{
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, array)
-
-    // set the input connection from which metadata such as arrays
-    // and time steps are taken from.
+    ///@}
+
+    /** @anchor target_input
+     * @name target_input
+     * Set the input connection from which metadata such as arrays
+     * and time steps are taken from.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(int, target_input)
-
-    // set the interpolation mode used in transfering
-    // data between meshes of differing resolution.
-    // in nearest mode value at the nearest grid point
-    // is used, in linear mode bi/tri linear interpolation
-    // is used.
-    enum {nearest=0, linear=1};
+    ///@}
+
+    /** list the interpolation modes used in transfering
+     *  data between meshes of differing resolution.
+     *  In nearest mode value at the nearest grid point
+     *  is used, in linear mode bi/tri linear interpolation
+     *  is used.
+     */
+    enum
+    {
+        /** 0 */
+        nearest=0,
+        /** 1 */
+        linear=1
+    };
+
+    /** @anchor interpolation_mode
+     * @name interpolation_mode
+     * Set the interpolation_mode mode. default is nearest
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(int, interpolation_mode)
+    ///@}
+
     void set_interpolation_mode_nearest(){ interpolation_mode = nearest; }
     void set_interpolation_mode_linear(){ interpolation_mode = linear; }