Как переопределить автоматически созданные данные документации для Boost :: Python? - PullRequest
Новая
       5

Как переопределить автоматически созданные данные документации для Boost :: Python?

9 голосов
/ 24 мая 2011

В настоящее время я работаю над созданием модуля на 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.

1 Ответ

19 голосов
/ 24 мая 2011
  • Используйте класс 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 */);
}
...