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

elbashandy · 2020-11-13T21:16:49Z

Resolves #478

elbashandy · 2020-11-13T23:56:49Z

I found a library called Exhale that converts Doxygen generated documentation into Sphinx docs using Breathe. However, after playing with Exhale, I realized that it might not be the right tool for us because it is pretty sensitive to any Doxygen errors, and TECA isn't fully documented properly in the style that Doxygen expects.

I think that Breathe might be the right choice to begin with as we can selectively choose the Algorithms & the software utilities that we want to expose in the documentation (Exhale tries to show everything.)

To show an example of what Doxygen & Breathe generate, I hosted some static pages of what I have in mind on how TECA should showcase the framework elements. This is still an early stage and it's not fully documented yet. You will find that I pretty much followed TECA's current organizational scheme [alg, core, data, io, system].

https://elbashandy.github.io/html/framework/framework.html

elbashandy · 2020-12-17T19:42:23Z

Creating a list of files that need to conform to Doxygen's documentation style:

Algorithms:

Core:

Data

I/O

elbashandy · 2020-12-17T19:44:00Z

@taobrienlbl @burlen feel free to modify the list that I documented above. I am going to go over this list one by one to make sure that the code documentation is picked up by Doxygen.

elbashandy · 2020-12-17T23:57:22Z

@taobrienlbl @burlen I want to take your opinion to discuss several approaches to choose from on how to document TECA macro expanded functions.

The 1st approach is a basic one which I manually specify the function names that I want to document:

/*! \fn set_component_variable(const std::string &v)

       set the name of the input array.
*/
/*! \fn get_component_variable() const

       get the name of the input array.
*/
TECA_ALGORITHM_PROPERTY(std::string, component_variable)

or we can modify the macro definition so that we can add a comment block above each generated function.
2nd approach:

#define TECA_ALGORITHM_PROPERTY(T, NAME, DESCRIPTION) \
                                                      \
/*! set DESCRIPTION */                                \
void set_##NAME(const T &v)                           \
{                                                     \
    if (this->NAME != v)                              \
    {                                                 \
        this->NAME = v;                               \
        this->set_modified();                         \
    }                                                 \
}                                                     \
                                                      \
/*! get DESCRIPTION */                                \
const T &get_##NAME() const                           \
{                                                     \
    return this->NAME;                                \
}

TECA_ALGORITHM_PROPERTY(std::string, component_variable,
        the name of the input array.)

I am leaning towards the 2nd approach as it is much cleaner and straightforward. However, it is less flexible because it uses the same description body (Unless of course we add an additional parameter to the macro - TECA_ALGORITHM_PROPERTY(T, NAME, DESCRIPTION_1, DESCRIPTION_2)).

Whatever approach we are going to use is going to take some effort to apply to all files. So hearing your opinion will be very much appreciated before I commit to one approach. Thanks :)

burlen · 2020-12-18T17:17:54Z

@taobrienlbl @burlen I want to take your opinion to discuss several approaches to choose from on how to document TECA macro expanded functions.

The 1st approach is a basic one which I manually specify the function names that I want to document:
...
or we can modify the macro definition so that we can add a comment block above each generated function.
...

With regard to the TECA_ALGORITHM_PROPERTY and TECA_ALGORITHM_VECTOR_PROPERTY macros, I would like to suggest the following alternative.

Annotate each function in the macro with a terse description of what the function does using the algorithm property name as passed into the macro. Then use the grouping mechanism to provide the main documentation for the property. Include an anchor so that the property may be linked to elsewhere.

Also please use the so called javadoc /** */ style doxygen markup.

An illustrative example follows:

#ifndef doxtest_h
#define doxtest_h

#define SET(_T, _N)                             \
    /** set the @ref _N algorithm property. */  \
    void set_  ## _N ( _T v)                    \
    { this-> _N = v; }                          \
                                                \
    /** get the @ref _N algorithm property. */  \
    _T get_ ## _N ()                            \
    { return this-> _N; }

/// Solves A*x = b via Jaccobi iteration.
/**
 * doxtest is a class that lets us try different doxygen documentation formats.
 * it's for our own internal use.  this is a long and rambling description.
 *
 * the @ref error_tolerance and @ref max_iter  properties control the solver.
*/
class doxtest
{
public:
    doxtest();
    ~doxtest();

    /** @anchor error_tolerance
     * @name error_tolerance
     * Sets the tolerance used for solver convergence. When the error
     * between two successive iterations is less than or equal to this value
     * then solver execution is stopped.
     */
    ///@{
    SET(double, error_tolerance)
    ///@}

    /** @anchor max_iter
     * @name max_iter
     * Sets the maximum number of sover iterations. When this number of                                                                                                                                                                                                                      
     * iteration is reached before the desired error tolerance is acheived the
     * solver will error out.
     */
    ///@{
    SET(int, max_iter)
    ///@}

    /** run the solver. if the solver converges to error_tolerance in less than max_iter iterations
     * then the solve was successful. Returns 0 if successful and non-zero otherwise.
     */
    int solve();

    /** print the class parameters.
     * sends the values to stderr
     */
    void print();

private:
    double error_tolerance;
    int max_iter;
};

#endif

and this is what it looks like

what does @taobrienlbl think?

elbashandy · 2020-12-18T22:08:26Z

@burlen great suggestion! Thank you.

burlen

Hi Abdel, Since you'll be working on getting this work in, I went ahead and marked a few things
that I saw.

burlen · 2021-03-10T19:22:58Z

core/teca_algorithm_fwd.h

@@ -32,6 +32,7 @@ std::shared_ptr<T const> shared_from_this() const   \
 }

 #define TECA_ALGORITHM_CLASS_NAME(T)                \
+/** returns the string value "T" */                 \


this is a virtual method and can be overriden in dervied classes. it does not necessarily return "T". say instead: returns the name of the class.

burlen · 2021-03-10T19:27:58Z

core/teca_algorithm_fwd.h

+    }                                                 \
+}                                                     \
+                                                      \
+/** Get the @ref NAME algorithm property */           \


Get the value of the ...

burlen · 2021-03-10T19:28:07Z

core/teca_algorithm_fwd.h

-    return this->NAME;                   \
+#define TECA_ALGORITHM_PROPERTY(T, NAME)              \
+                                                      \
+/** Set the @ref NAME algorithm property */           \


Set the value of the ...

burlen · 2021-03-10T19:33:05Z

alg/teca_2d_component_area.h

+    |                            | | i.e. the background. This can be used to skip processing |
+    |                            | | of the background when desirable.                        |
+    +----------------------------+------------------------------------------------------------+
+@endrst


I'm not sold on the idea of using rst tables for this. What's the reason? Was it to test with Breathe?

Also, use @ref component_variable etc to make a link to the property's documentation

burlen · 2021-03-10T19:34:07Z

alg/teca_2d_component_area.h

@@ -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.


Use doxygen style comments and grouping here as well.

The documentation should read something to the effect:

Set/get the name of the variable containing the connected component labels

burlen · 2021-03-10T19:43:45Z

alg/teca_cartesian_mesh_regrid.h

+    /** 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)


see my comments about threshold_mode above, all the same applies here

burlen · 2021-03-10T19:47:14Z

alg/teca_dataset_diff.h

-    //            0            otherwise
+    /** @anchor tolerance
+     * @name tolerance
+     * Set tolerance. Relative tolerance below which two floating-point


Set the relative tolerance ...

Note: this class has changed substantially and you might be better off copying the things you want to keep than trying to resolve conflicts

burlen · 2021-03-10T19:48:30Z

alg/teca_dataset_diff.h

@@ -101,7 +114,7 @@ class teca_dataset_diff : public teca_algorithm
        const teca_metadata &request) override;

 private:
-    // Tolerance for equality of field values.
+    /** Tolerance for equality of field values. */


this is documented via the algorithm property, we should probably remove this one

burlen · 2021-03-10T19:53:18Z

alg/teca_cartesian_mesh_source.h

-    // default is 32 bit floating point. Use
-    // teca_variant_array_type<NT>::get() to get specific type
-    // codes for C++ POD types NT.
+    /** @anchor coordinate_type_code


Ooops. I also made major revisions to teca_cartesian_mesh_source class and its documentation. I've added and revised the documentation in addition to the stylistic changes you made. To avoid losing the new text during conflict resolution, please drop these changes.

burlen · 2021-03-10T19:54:04Z

doc/rtd/index.rst

@@ -15,10 +15,11 @@ largest scale on DOE HPC systems.
    Storm Tracks Generated by TECA

 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2


Unless you have a compelling reason for the change I'd prefer to leave at 3 for now.

elbashandy added 2 commits December 17, 2020 13:44

Integrating Doxygen/Breathe with TECA's rtd

01e8502

Finished teca_2d_component_area

db3f3a5

elbashandy force-pushed the doxygen_rtd_integration branch from ad5a7c9 to db3f3a5 Compare December 17, 2020 21:44

elbashandy added 3 commits January 11, 2021 15:52

clean up: Added documentation to several algorithms

3f151c4

squash: Supporting Doxygen at additional teca algorithms

bc6cea7

Installed Exhale and tried documenting teca_2d_component_area only

c704455

burlen reviewed Mar 10, 2021

View reviewed changes

elbashandy mentioned this pull request Mar 12, 2021

Doxygen rtd integration [second attempt] #574

Merged

This was referenced Apr 6, 2021

clean up and merge the Breathe example #594

Closed

doxygen style for algorithm properties #595

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

elbashandy commented Nov 13, 2020

elbashandy commented Nov 13, 2020

elbashandy commented Dec 17, 2020 •

edited

Loading

elbashandy commented Dec 17, 2020 •

edited

Loading

elbashandy commented Dec 17, 2020

burlen commented Dec 18, 2020

elbashandy commented Dec 18, 2020

burlen left a comment

burlen Mar 10, 2021

burlen Mar 10, 2021

burlen Mar 10, 2021

burlen Mar 10, 2021

burlen Mar 10, 2021

burlen Mar 10, 2021

burlen Mar 10, 2021

burlen Mar 10, 2021

burlen Mar 10, 2021

burlen Mar 10, 2021

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

Are you sure you want to change the base?

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

Conversation

elbashandy commented Nov 13, 2020

elbashandy commented Nov 13, 2020

elbashandy commented Dec 17, 2020 • edited Loading

elbashandy commented Dec 17, 2020 • edited Loading

elbashandy commented Dec 17, 2020

burlen commented Dec 18, 2020

elbashandy commented Dec 18, 2020

burlen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elbashandy commented Dec 17, 2020 •

edited

Loading

elbashandy commented Dec 17, 2020 •

edited

Loading