如何覆盖Boost::Python自动生成的文档字符串数据？

Question

我现在正在开发一个基于C++的Python模块。我发现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

虽然输出的文档对我这个开发者来说很有价值，但对最终用户来说，大部分内容都是噪音，甚至更糟，会让人困惑。（比如，我的用户并不关心某个方法的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 */);
}