[C++-sig] boost::python + epydoc

[Neal Becker]

Stefan Seefeld wrote:

> Neal Becker wrote:
>> I'm using epydoc-3.0alpha3.  I know we've talked about this before, but I
>> don't think the issue was resolved.
>> 
>> When using epydoc with boost::python doc strings, you have to turn off
>> signatures:
>> 
>>   docstring_options doc_options (true, false);
>> 
>> Otherwise, it seems epydoc is confused.
>> 
>> Is there any resolution to this issue?  I'd rather not have to turn off
>> the signatures to add my documentation.
> 
> What is the issue with epydoc ? Do other documentation tools (happydoc,
> say) work fine ? (I know epydoc supports both, parsing as well as
> introspection to extract documentation. Is that related ?)
> 
> Thanks,
> Stefan
> 

I have not had time to analyze the problem.  The symptoms are that this
code, for example:

  def ("corr",
&corr<ublas::vector<Complex>,ublas::vector<Complex>,ublas::vector<Complex>
>,
       default_call_policies(), 
       (
        arg ("in"),
        arg ("coef"),
        arg ("size"),
        arg ("stride")=1
        ),
       "correlate an input against reference coeff.\n"
       "@param in: input.\n"
       "@type in: vector_Complex\n"
       "@param coef: reference pattern\n"
       "@type coef: vector_Complex\n"
       "@param size: size of the output desired\n"
       "@type size: int\n"
       "@param stride: stride for input (def=1)\n"
       "@type stride: int\n"
       );

When docstring_options is not used, epydoc doesn't pick up @param, @type,
and simply renders these literally into the docstring, but when sig is
turned off, these are picked up and interpreted correctly by epydoc.