Sphinx 没有正确格式化重载的 Python 函数参数答案

【问题标题】：Sphinx is not formatting overloaded Python function parameters correctlySphinx 没有正确格式化重载的 Python 函数参数
【发布时间】：2021-05-31 13:22:02
【问题描述】：

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

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

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

这就是它的样子：

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

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

为此，格式已全部关闭，尤其是 Parameters 和 Returns 的显示方式。这就是它的样子。

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

【问题讨论】：

首先请将图片添加到问题中（编辑模式下的“山”图标）。您使用的是哪个版本的 doxygen？看看这是否可能是一个 doxygen 问题：doxygen 的 HTML 输出中的结果如何？

标签： python-sphinx doxygen pybind11

【解决方案1】：

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

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"

【讨论】：