Sphinx is not formatting overloaded Python function parameters correctly

Question

I am using doxygen + Sphinx to generate documentation for some Python bindings I have written. The Python bindings are written using pybind11.

When I write my documentation string for a non overloaded function, it formats properly. Here is an example:

// Pybind11 python bindings.
// Module and class defined above...

.def("get_similarity", [](SDK &sdk, const Faceprint& faceprint1, const Faceprint& faceprint2) {
            float similarity;
            float probability;
            ErrorCode status = sdk.getSimilarity(faceprint1, faceprint2, probability, similarity);
            return std::make_tuple(status, probability, similarity);
        },
             R"mydelimiter(
            Compute the similarity of the given feature vectors.

            :param feature_vector_1: the first Faceprint to be compared.
            :param feature_vector_2: the second Faceprint to be compared.
            :return: The see :class:`ERRORCODE`, match probability and similairty score, in that order. The match probability is the probability that the two faces feature vectors are a match, while the similairty is the computed similairty score.
        )mydelimiter",
            py::arg("feature_vector_1"), py::arg("feature_vector_2"))

This is what it looks like:

Nice output

When I write documentation for an overloaded function, the formatting is off. Here is an example:

        .def("set_image", [](SDK &sdk, py::array_t<uint8_t> buffer, uint16_t width, uint16_t height, ColorCode code) {
            py::buffer_info info = buffer.request();
            ErrorCode status =sdk.setImage(static_cast<uint8_t*>(info.ptr), width, height, code);
            return status;
        },
             R"mydelimiter(
            Load an image from the given pixel array in memory.
            Note, it is highly encouraged to check the return value from setImage before proceeding.
            If the license is invalid, the ``INVALID_LICENSE`` error will be returned.

            :param pixel_array: decoded pixel array.
            :param width: the image width in pixels.
            :param height: the image height in pixels.
            :param color_code: pixel array color code, see :class:`COLORCODE`
            :return: Error code, see :class:`ERRORCODE`
            )mydelimiter",
           py::arg("pixel_array"), py::arg("width"), py::arg("height"), py::arg("color_code"))

// Other overrides of set_image below...

The formatting is all off for this, in particular the way the Parameters and Returns are displayed. This is what it looks like.

Bad output

How can I get the set_image docs to look like the get_similarity docs?

First please add the pictures to the question (the "mountain" icon in edit mode). Which version of doxygen are you using? To see whether this might be a doxygen problem: how do the results like in the HTML output of doxygen? — albert, Mar 02 '21 at 08:35

score 0 · Accepted Answer · answered Mar 03 '21 at 01:13

I'm not sure how to properly solve the problem, but here is a hack I used to make them appear to be the same. Basically, I hard coded the formatting:

R"mydelimiter(
Load an image from the given pixel array in memory.
Note, it is highly encouraged to check the return value from setImage before proceeding.
If the license is invalid, the ``INVALID_LICENSE`` error will be returned.

:Parameters: 
- **pixel_array** - decoded pixel array.
- **width** - the image width in pixels.
- **height** - the image height in pixels.
- **color_code** - pixel array color code, see :class:`COLORCODE`
:Returns: 
 Error code, see :class:`ERRORCODE`
)mydelimiter"

Sphinx is not formatting overloaded Python function parameters correctly

1 Answers1