c++ - 如何覆盖为 Boost::Python 自动创建的文档字符串数据？

Question

我目前正在为 Python 开发一个基于 C++ 的模块。我发现 Boost::Python 对于我想要完成的事情来说工作得很好。但是，我现在遇到了由 Boost::Python 生成的文档字符串的一些问题。给定以下 Boost::Python 定义:

BOOST_PYTHON_MODULE(gcsmt)
{
class_<gcsmt::Units>("Units", "Sets the units used as input.", no_init)
    .def("PrintSupported", &gcsmt::Units::printSupported, "Print out all supported units.")
    .def("SetDefault", &gcsmt::Units::setDefaultUnit, "Sets the default unit to be used for inputs/outputs.")
    .staticmethod("PrintSupported")
    .staticmethod("SetDefault")
    .def(self_ns::str(self_ns::self))
    ;
}

如果我在 Python 中编译、加载我的模块，并获得有关 gscmt.Units 类的帮助，输出如下:

>>> help(gcsmt.Units)

Help on class Units in module gcsmt:

class Units(Boost.Python.instance)
 |  Sets the units used as input.
 |  
 |  Method resolution order:
 |      Units
 |      Boost.Python.instance
 |      __builtin__.object
 |  
 |  Methods defined here:
 |  
 |  __reduce__ = <unnamed Boost.Python function>(...)
 |  
 |  __str__(...)
 |      __str__( (Units)arg1) -> object :
 |      
 |          C++ signature :
 |              _object* __str__(gcsmt::Units {lvalue})
 |  
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |  
 |  PrintSupported(...)
 |      PrintSupported() -> None :
 |          Print out all supported units.
 |      
 |          C++ signature :
 |              void PrintSupported()
 |  
 |  SetDefault(...)
 |      SetDefault( (UnitType)arg1, (str)arg2) -> None :
 |          Sets the default unit to be used for inputs/outputs.
 |      
 |          C++ signature :
 |              void SetDefault(gcsmt::unitType,std::string)
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  __init__ = <built-in function __init__>
 |      Raises an exception
 |      This class cannot be instantiated from Python
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from Boost.Python.instance:
 |  
 |  __dict__
 |  
 |  __weakref__
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes inherited from Boost.Python.instance:
 |  
 |  __new__ = <built-in method __new__ of Boost.Python.class object>
 |      T.__new__(S, ...) -> a new object with type S, a subtype of T

虽然输出的大部分文档对作为开发人员的我来说很有值(value)，但对于最终用户来说，其中大部分都是杂音，甚至更糟，令人困惑。 (例如，我的用户不关心给定方法的 C++ 签名是什么，他们也不需要查看方法解析顺序或显示的其他隐藏方法)。有没有什么方法可以覆盖并减少由 Boost::Python 设置的文档的级别/冗长程度？理想情况下，我希望我的文档看起来像这样:

>>> help(gcsmt.Units)

Help on class Units in module gcsmt:

class Units
 |  Sets the units used as input.
 |  
 |  PrintSupported() -> None :
 |      Print out all supported units.
 |  
 |  SetDefault( (UnitType)arg1, (str)arg2) -> None :
 |      Sets the default unit to be used for inputs/outputs.

Answer 1

• 使用 boost::python::docstring_options 类来定义自动创建的文档字符串选项。
• 所有 def 函数都将文档字符串作为最后一个参数。
• 所有class_定义都将类文档字符串作为最后一个参数

即:

using boost::python;
BOOST_PYTHON_MODULE(foo)
{
  // This will enable user-defined docstrings and python signatures,
  // while disabling the C++ signatures
  docstring_options local_docstring_options(true, true, false);

  class_<Bar>("Bar", init<>(), "Bar class" /* class docstring here */ )
    .def("foobar", &Bar::foobar, "foobar function" /* function docstring here */);
}