boost :: python中静态属性的文档字符串

Question

我已经为我的c ++应用程序的核心功能添加了python绑定，现在我正在尝试在各处添加docstrings，以便我可以使用sphinx自动记录暴露的python。

它几乎可以工作，但是当我有静态属性时，（使用add_static_property方法添加）我无法覆盖docstring。一个例子是我的一个属性，它返回一个浮点数：

MyClass.static_property.__doc__
float(x) -> floating point number

当我使用def方法或属性方法时，最后一个参数允许我添加我的docstring。有谁知道为什么静态属性不能这样做？有没有办法允许他们？

非常感谢

Answer 1

Boost.Python不支持它，因为Python不支持它。正如PEP 257中所述：

  

docstring是一个字符串文字，作为模块，函数，类或方法定义中的第一个语句出现的。这样的文档字符串成为该对象的__doc__特殊属性。

Python类属性变量是一个引用，而不是一个对象本身。因此，引用没有__doc__属性，但它引用的对象可以。例如，请考虑以下事项：

>>> class Spam:
...     egg = 42
... 
>>> assert Spam.egg.__doc__ == int.__doc__

---

在Python中，方法和property()都是对象，因此可能包含docstring。 Boost.Python boost::python::class_::add_static_property()函数有点用词不当，因为Python没有静态属性。 C ++静态数据成员的功能等价物是Python的类变量。

作为替代方案，请考虑在类docstring中记录类变量，因为类变量的文档特定于包含类的上下文。这是一个完整的例子：

#include <boost/python.hpp>

// Mockup class.
struct spam
{
  static int egg;
  int parrot;
};

int spam::egg = 0;


BOOST_PYTHON_MODULE(example)
{
  namespace python = boost::python;

  // Documentation for this module.
  python::scope().attr("__doc__") = 
    ".. module:: example\n"
    "\n"
    "   :platform: Unix, Windows\n"
    "   :synopsis: An example module for Boost.Python docstrings.\n"
    "\n"
    ;

  const char* py_spam_doc =
    "A mockup ``Spam`` class.\n"
    "\n"
    "This class is just used for demonstrating docstrings.\n"
    "\n"
    ":cvar egg: The egg class variable's documentation.\n"
    "\n"
    ;
  python::class_<spam>("Spam", py_spam_doc)
    .add_property("parrot", &spam::parrot,
      "The parrot instance variable's documentation.")
    .add_static_property("egg",
      python::make_getter(&spam::egg),
      python::make_setter(&spam::egg))
    ;
}

运行sphinx-quickstart并启用autodoc后，修改index.rst以包含所需的Python组件。在这种情况下，我补充说：

.. automodule:: example
   :noindex:

.. autoclass:: Spam
   :members:

make html生成了以下代码段：