Блог

Я использую doxygen Sphinx для создания документации для некоторых написанных мной привязок Python. Привязки Python записываются с использованием pybind11.

Когда я пишу свою строку документации для не перегруженной функции, она правильно форматируется. Вот пример:

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

.def("get_similarity", [](SDK amp;sdk, const Faceprintamp; faceprint1, const Faceprintamp; 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 amp;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 документы?

Я не уверен, как правильно решить проблему, но вот хак, который я использовал, чтобы они выглядели одинаково. В принципе, я жестко запрограммировал форматирование:

 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"