Sphinx 未正确格式化重载的 Python 函数参数

问题描述

我正在使用 doxygen + Sphinx 为我编写的一些 Python 绑定生成文档。 Python 绑定是使用 pybind11 编写的。

当我为非重载函数编写文档字符串时，它的格式正确。 下面是一个例子：

// 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,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"))

这是它的样子：

当我为重载函数编写文档时，格式是关闭的。下面是一个例子：

        .def("set_image",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...

格式已全部关闭，特别是 Parameters 和 Returns 的显示方式。这是它的样子。

如何让 set_image 文档看起来像 get_similarity 文档？

解决方法

我不确定如何正确解决问题，但这里有一个我用来使它们看起来相同的 hack。基本上，我对格式进行了硬编码：

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"