epydoc-devel — Discussions about epydoc development

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi Edward!

Am Freitag, 11. Mai 2007 16:10:46 schrieb Edward Loper:
> On May 11, 2007, at 10:05 AM, Hans Meine wrote:
> > What I wanted to say is that I have found several examples where
> > the latter (the complete docstring) is missing.
>
> Can you please file a bug report w/ these two examples?

Voila:
http://sourceforge.net/tracker/index.php?func=detail&aid=1732610&group_id=32455&atid=405618

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] [C++-sig] Better introspection/apidoc extraction support?

[Hans M. <me...@in...>]

Hi Ralf!

Am Dienstag, 22. Mai 2007 19:14:42 schrieb Ralf W. Grosse-Kunstleve:
> Sorry, this looks like more work than I'm able to squeeze in. I was hoping
> for a well-established, time-tested API, but it looks more like work in
> progress.

That's a pity, but I can understand it.  OTOH, I don't think there is much 
progress ATM, as long as PEP 362 is not implemented.  (Is there a reason you 
did not reply to my later post where I mentioned 
http://www.python.org/dev/peps/pep-0362/ - I just want to make sure you saw 
it.)

I indeed wrote a parser for the C++ signatures for epydoc, but it is quite 
complicated since I have to
- parse arbitrary C++ types (templates with argument literals,
  namespaces, ...), which made me hack together a rather largish
  pyparsing-based parser (and as you know, writing a C++ parser is not what
  you wanna do..)
- parse arbitrary Python __repr__ output for the default arguments.
  Again, that is not doable with just regular expressions, also the __repr__
  can be basically anything, so it cannot be 100% safe.

It would be much better if there was an API to extract argument names and 
default values.

> The current docstring support isn't all that complicated. Look in
> boost/libs/python/src/object/function.cpp, mainly function::signature().

When using epydoc, I noticed that the resulting docstrings are no valid reST 
anymore if the original docstring does not end with a \n:

"""foo bar
C++ signature:
   test(void) -> void"""

However, this would be a valid description list:

"""foo bar

C++ signature:
   test(void) -> void"""

Would it make sense to just add two \n instead of one in
libs/python/src/object/function.cpp:510?

Or look at the attached patch, which also cares about docstrings to which a \n 
has manually been appended for boost 1.34.0beta + epydoc support.

That does not yet lead to a very pretty output, but it is a minimal change 
that makes epydoc w/ reST work at least, without further modifications.

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi again!

Am Freitag, 18. Mai 2007 16:28:43 schrieb Hans Meine:
> Am Freitag, 11. Mai 2007 00:38:02 schrieb Edward Loper:
> > Perhaps boost and/or sip could be encouraged to include some
> > introspectable value that can be used to find the signature?  Either
> > by automatically including a signature at the beginning of the
> > __doc__ attribute, or by adding a new attribute to the object?  If
> > they did that, I'd be happy to add support to epydoc for reading it.
>
> I wrote a parser for the C++ signatures, using pyparsing.[*]

I knew that the parser was not perfect when I wrote this, but I wanted to have 
some feedback.

Now I realized there is a specific flaw: In order to let my test suite run 
(parsing 206 random C++ signatures from a real-life extension module), I 
extended the parser to grok e.g. python list literals, which is needed for 
the default arguments.  However, I should have separated parsers for C++ 
literals (template arguments in the type specs) and python literals (default 
values). :-(

Alas, the only existing C++ parser I could find is part of 
http://synopsis.fresco.org/, and I would still need pyparsing for the special 
C++ signature format with mixed C++/python expressions.

BTW: How does epydoc handle default arguments with commas, e.g.

"""test(a, b, c = [1,2,3], d = None)

Foo bar baz..."""

AFAICS, that cannot be done with regular expressions very easily?! (OK, I 
chose numbers as list contents, which are no valid identifiers.  I could try 
harder though. ;-) )

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi Edward!

Am Freitag, 11. Mai 2007 00:38:02 schrieb Edward Loper:
> Perhaps boost and/or sip could be encouraged to include some
> introspectable value that can be used to find the signature?  Either
> by automatically including a signature at the beginning of the
> __doc__ attribute, or by adding a new attribute to the object?  If
> they did that, I'd be happy to add support to epydoc for reading it.

I wrote a parser for the C++ signatures, using pyparsing.[*]
Even if the BPL people would not implement other support, that could bring 
users a working solution now, with boost 1.34.0 (CVS or beta, widely used).

I attach the code for you consideration; the epydoc_*.diff for 
docstringparser.py is far from finished, but hopefully shows what I mean.

[*] Of course, pyparsing would be a new dependency, but C++ signatures cannot 
be parsed with regular expressions at all, IMO.  I tried to make pyparsing be 
only loaded if epydoc is ran on code with C++ signatures embedded, so there 
could be a "pyparsing missing" warning just in that case.

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] How to document properties?

[Hans M. <me...@in...>]

Am Mittwoch, 16. Mai 2007 13:57:11 schrieb Daniele Varrazzo:
> >> As you can read here:
> >> http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/#api-doc
> >>ume ntation I don't like the large list of "variables" either, which are
> >> in fact
> >> constants and some kind of enum. (Please tell me a better Python API for
> >> such constants if you know one.)
>
> You may group such constants using group markers. See
> http://epydoc.sourceforge.net/epydoc.html#grouping-and-sorting:
>
>     #{ polygon types
>     ptPolyline    = 1
>     ptBox         = 2
>     ptPolygon     = 3
>     ptArcBox      = 4
>     ptPictureBBox = 5

What a pity that I cannot cross-reference the functions these "constants" are 
to be used in in the #{ caption:

#{ polygon types constants (cf. `PolylineBase.changeType`)

does not work (reST mode). :-(

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] How to document properties?

[Daniele V. <pi...@de...>]

> BTW: The link helped me a lot, too!  Believe it or not, but I did not yet
> find
> http://epydoc.sourceforge.net/epydoc.html, since I was reading "Epydoc
> Manual" as a caption in the style of "Related Information", and I was only
> looking at the "smaller" http://epydoc.sourceforge.net/manual-###.html links
> below. ;-/

Thank you for the feedback: we may update the homepage as:

    <a>Epydoc manual (single page)</a>

    One chapter per page:

        * <a>Installing Epydoc</a>
        * <a>Using Epydoc</a>
        * ...

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

Re: [Epydoc-devel] How to document properties?

[Hans M. <me...@in...>]

Am Mittwoch, 16. Mai 2007 13:57:11 schrieb Daniele Varrazzo:
> You may group such constants using group markers. See
> http://epydoc.sourceforge.net/epydoc.html#grouping-and-sorting:
>
>     #{ polygon types
>     ptPolyline    = 1
>     ptBox         = 2
>     ptPolygon     = 3
>     ptArcBox      = 4
>     ptPictureBBox = 5

Thanks a lot, Daniele!

BTW: The link helped me a lot, too!  Believe it or not, but I did not yet find 
http://epydoc.sourceforge.net/epydoc.html, since I was reading "Epydoc 
Manual" as a caption in the style of "Related Information", and I was only 
looking at the "smaller" http://epydoc.sourceforge.net/manual-###.html links 
below. ;-/

> There is no such thing as an enum in Python, neither there are constants.
> Be explicit with how variables are expected to be used: call your groups
> "polygon types constants", for example.
Good idea, thanks.

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] How to document properties?

[Daniele V. <pi...@de...>]

> The "enum problem" mentioned below is a different topic and still unsolved:
>> As you can read here:
>> http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/#api-docume
>>ntation I don't like the large list of "variables" either, which are in
>> fact
>> constants and some kind of enum. (Please tell me a better Python API for
>> such constants if you know one.)

You may group such constants using group markers. See
http://epydoc.sourceforge.net/epydoc.html#grouping-and-sorting:

    #{ polygon types
    ptPolyline    = 1
    ptBox         = 2
    ptPolygon     = 3
    ptArcBox      = 4
    ptPictureBBox = 5

    #{ ellipse types
    etEllipseRadii    = 1
    etEllipseDiameter = 2
    etCircleRadius    = 3
    etCircleDiameter  = 4  ...

There is no such thing as an enum in Python, neither there are constants. Be
explicit with how variables are expected to be used: call your groups
"polygon types constants", for example.

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

Re: [Epydoc-devel] How to document properties?

[Hans M. <me...@in...>]

Hi!

I found a good partial solution that I wanted to try out anyways:

Am Montag, 14. Mai 2007 10:34:32 schrieb Hans Meine:
> class Object(object):
> 	"""Base class of all fig objects.  Handles common properties like
>
> 	- lineStyle (see `lineStyleXXX` constants)
> 	- lineWidth (1/80th inch)
> 	- styleValue (dash length / dot gap ratio), in 1/80th inches
> 	- penColor, fillColor (see `colorXXX` constants)
> 	- fillStyle (see `fillStyleXXX` constants)
> 	- depth (0-999)
> 	- joinStyle (see `joinStyleXXX` constants)
> 	- capStyle (see `capStyleXXX` constants)
> 	- forwardArrow/backwardArrow (`Arrow` objects)"""

	__slots__ = 
["lineWidth", "penColor", "fillColor", "depth", "penStyle", "fillStyle",
				 "styleValue", "joinStyle", "capStyle", "forwardArrow", "backwardArrow"]

> 	def __init__(self):
> 		self.lineStyle = lineStyleDefault
> 		self.lineWidth = 1
> 		self.penColor = colorDefault
> 		self.fillColor = colorDefault
> 		self.depth = 50
> 		self.penStyle = 0 # not used
> 		self.fillStyle = fillStyleNone
> 		self.styleValue = 3.0
> 		self.joinStyle = 0
> 		self.capStyle = 0
> 		self.forwardArrow = None
> 		self.backwardArrow = None
>
> As you can see (yes, this is the complete API), the user is supposed to
> directly access these properties of XFig objects.  However, I would like to
> have them listed in the API documentation in the "properties" section.

This is accomplished with the __slots__ definition, which creates descriptor 
properties (http://docs.python.org/ref/descriptors.html#descriptors).

It also makes the API a little bit more pythonic and more clean, since in my 
case it is a good thing that setting other attributes becomes forbidden.

However, I am now looking for a convenient way of adding docstrings to the 
automatically generated properties.

The "enum problem" mentioned below is a different topic and still unsolved:
> As you can read here:
> http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/#api-docume
>ntation I don't like the large list of "variables" either, which are in fact
> constants and some kind of enum. (Please tell me a better Python API for
> such constants if you know one.)

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] [C++-sig] Better introspection/apidoc extraction support?

[Hans M. <me...@in...>]

Hi!

Am Dienstag, 15. Mai 2007 14:12:07 schrieb English, Mark:
> For an introspection example, there was a signature.py drifting around
> which I'm having trouble tracking down, written I believe by Neel
> Krishnaswami. There's a copy here:
> http://funformkit.sourceforge.net/FunFormKit/Signature.py

That looks like a predecessor / alternative to the std. 'inspect' module.
(And does not yet work with boost::python or course.)

> Speaking of signatures, have you looked at the draft Pep 362 ?
> http://www.python.org/dev/peps/pep-0362/

That PEP is very interesting indeed.  Since it describes a complete API, it 
looks like a perfect implementation goal for BPL.  (Eager/lazy creation does 
not really matter here, as long as BPL functions get a proper __signature__ 
attribute.)  Ralf, what do you think?

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi!

Am Dienstag, 15. Mai 2007 13:45:52 schrieb Daniele Varrazzo:
> To overcome this problem, i suggest you to add a module variable
> "__docformat__ = 'restructuredtext'" in your modules and to run epydoc with
> the "--docformat=plaintext" option. This way docstrings in boost-generated
> modules will not be parsed as reST.

Hehe, but I *want* to parse reST in the extension module.
I will use the attached patch for now.  That could be the right position to 
add further BPL (boost::python library) support, like the following:

   sig_re = _SIGNATURE_RE

    boost_signature_pos = doc_source.docstring.find("C++ signature:\n    ")
    if boost_signature_pos >= 0:
        boost_signature = doc_source.docstring[boost_signature_pos+19:]
        doc_source.docstring = doc_source.docstring[:boost_signature_pos]
        sig_re = _BOOST_SIGNATURE_RE # _SIGNATURE_RE + type support

   m = sig_re.match(doc_source.docstring)
   ...

Alas, there is one important case which I did not think about yet: Overloaded 
functions get multiple signatures appended:

'norm(vector)\nmagnitude(vector)\n\nCalculate the L2 norm / length of a vector 
(or scalar).\nC++ signature:\n    norm(vigra::PythonVectorView<float> 
vector) -> float\nC++ signature:\n    norm(double) -> double\nC++ signature:
\n    norm(vigra::TinyVector<double, 2>) -> double\nC++ signature:\n    
norm(vigra::TinyVector<double, 3>) -> double\nC++ signature:\n    
norm(vigra::TinyVector<double, 4>) -> double'

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] [C++-sig] Better introspection/apidoc extraction support?

[Hans M. <me...@in...>]

Hi!

Am Montag, 14. Mai 2007 17:59:00 schrieb Ralf W. Grosse-Kunstleve:
> I did the implementation of the "docstring_options" feature. I'm not aware
> of plans to work on this, but I'm interested to at least learn what could
> be done to better support epydoc. If it is not too time-consuming I'd be
> willing to work on it a bit.

Great!

> > The epydoc developers would like to support boost::python function
> > introspection.  In boost 1.34.0, there is support for C++ signatures
> > appended to the docstrings, but it would be better AFAICS if
> > boost::python would additionally provide means for extracting the
> > argument names and default values via ("half-private") attributes,
> > similar to CPython.
>
> How exactly does this work?  Are there web pages about this?

Not that I know of.  AFAICS, there is no public API for that (that's why I 
wrote "half-private"), but if you look at a functions func_code.co_XXX and 
func_defaults properties, you see that there is a lot of internal information 
available in CPython.

Then, there is the inspect module (implemented in python), which uses the 
above internal stuff to offer a more convenient API.  E.g. 
inspect.getargspec() uses func_code.co_varnames[:func_code.co_argcount] to 
query the argument names, func_code.co_flags to determine whether the 
function has *args or **kwargs parameters (4/8 bitflags), ...

I would think that basically *any* API within boost::python functions would be 
OK, since there is no official way beyond inspect.  (Of course, it would be 
best if the inspect module would become compatible with boost::python some 
day, so apidoc projects do not have to duplicate code..)

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi again!

Am Freitag, 11. Mai 2007 00:38:02 schrieb Edward Loper:
> Perhaps boost and/or sip could be encouraged to include some
> introspectable value that can be used to find the signature?  Either
> by automatically including a signature at the beginning of the
> __doc__ attribute, or by adding a new attribute to the object?  If
> they did that, I'd be happy to add support to epydoc for reading it.
I posted a request for that on the c++-sig list (boost::python development 
list), but so far, nobody volunteered:
http://mail.python.org/pipermail/c++-sig/2007-May/012355.html

(Yes, I know the signature-in-docstring sentence is wrong, since they are not 
discouraged in extension modules AFAICS.)

Would you be willing to add support for the extended docstrings with C++ 
signature?  Now that I built the new boost::python 1.34.0beta, I am swamped 
in docutils warnings:

+---------------------------------------------------------------------------------------------------------------
| File /home/meine/local-SuSE-10.2/lib/python2.4/hourglassmodule.so, in 
hourglass.DynamicCostQueue.empty
|   Warning: Unexpected indentation.
|
+---------------------------------------------------------------------------------------------------------------
| File /home/meine/local-SuSE-10.2/lib/python2.4/hourglassmodule.so, in 
hourglass.DynamicCostQueue.insert
|   Warning: Unexpected indentation.
|
...

This is because the docstrings now look like this one:
> Return True iff pop() can deliver another pair.
> C++ signature:
>     empty(vigra::DynamicCostQueue {lvalue}) -> bool

-- 
Ciao, /  /
     /--/
    /  / ANS

[Epydoc-devel] How to document properties?

[Hans M. <me...@in...>]

Hi!

On the page I recently posted, I note a problem I currently have -
e.g. I want to document my base class for XFig objects:

class Object(object):
	"""Base class of all fig objects.  Handles common properties like
	
	- lineStyle (see `lineStyleXXX` constants)
	- lineWidth (1/80th inch)
	- styleValue (dash length / dot gap ratio), in 1/80th inches
	- penColor, fillColor (see `colorXXX` constants)
	- fillStyle (see `fillStyleXXX` constants)
	- depth (0-999)
	- joinStyle (see `joinStyleXXX` constants)
	- capStyle (see `capStyleXXX` constants)
	- forwardArrow/backwardArrow (`Arrow` objects)"""

	def __init__(self):
		self.lineStyle = lineStyleDefault
		self.lineWidth = 1
		self.penColor = colorDefault
		self.fillColor = colorDefault
		self.depth = 50
		self.penStyle = 0 # not used
		self.fillStyle = fillStyleNone
		self.styleValue = 3.0
		self.joinStyle = 0
		self.capStyle = 0
		self.radius = -1
		self.forwardArrow = None
		self.backwardArrow = None

As you can see (yes, this is the complete API), the user is supposed to 
directly access these properties of XFig objects.  However, I would like to 
have them listed in the API documentation in the "properties" section.
Can you advise me how to approach this?

http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/apidox/fig.Object-class.html

As you can read here:
http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/#api-documentation
I don't like the large list of "variables" either, which are in fact constants 
and some kind of enum. (Please tell me a better Python API for such constants 
if you know one.)

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Am Donnerstag, 10. Mai 2007 20:57:17 schrieb Daniele Varrazzo:
> Also notice that the PEP 275 discourages to duplicate the function
> signature in the docstring for pure Python modules: it can be retrieved by
> introspection.

Do you really mean "PEP 275: Switching on Multiple Values"?

..Ah, now I found it, it is: 257 - Docstring Conventions!
  http://www.python.org/dev/peps/pep-0257/

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi Daniele!

Am Freitag, 11. Mai 2007 16:20:35 schrieb Daniele Varrazzo:
> Ok: this seems a bug. After the first paragraph there is not another
> paragraph but a block: this is probably creating some confusion.
Yeah, I already figured it was sth. like that.

(It is really amazing how much one has to adapt documentation to a specific 
documentation tool, or - to put it the other way round - how many possible 
ways of writing non-conventional documentation there are.  I already 
experienced the same with C++/Doxygen.)

BTW: I just ran epydoc on my fig.py module and put the documentation online, 
in case you are interested in another case study: 
http://kogs.informatik.uni-hamburg.de/~meine/software/figpy/

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Daniele V. <pi...@de...>]

> and I just found another one:

> 

> def parseGeometry(geometryString):

> 	"""Convenience function for parsing geometry strings of various

> 	formats::

> 

> 	  >>> fig.parseGeometry("320,240-640,480")

> 	  fig.Rect(320,240,640,480)

> 	  >>> fig.parseGeometry("50,50+50,50")

> 	  fig.Rect(50,50,100,100)

> 	  >>> fig.parseGeometry("40,40,320,240")

> 	  fig.Rect(40,40,320,240)

> 	  >>> r = fig.Rect(0,0,320,240)

> 	  >>> fig.parseGeometry(str(r)) == r

> 	  True

> 	"""

> 	ma = _re_geometry.match(geometryString)



Ok: this seems a bug. After the first paragraph there is not another paragraph but a block: this is probably creating some confusion. The following works fine instead::



    def parseGeometry(geometryString):

        """Convenience function for parsing geometry strings of various

         formats. Examples are::

             ...



I'll investigate. Thank you.



-- 

Daniele Varrazzo - Develer S.r.l.

http://www.develer.com

Re: [Epydoc-devel] Docstring parsing shortcomings

[Daniele V. <pi...@de...>]

> I agree.  While I wrote the above, the idea looked less and less like a good
> one to me. ;-)  However, I now changed this docstring for example:
>
>     """simplifyMapEdges(map, perpendicularDistEpsilon)
>     simplifyMapEdges(map, perpendicularDistEpsilon, maxStep)
>
>     Changes ..."""
>
> like this to mark the last argument as optional:
>
>     """simplifyMapEdges(map, perpendicularDistEpsilon[, maxStep])
>     ..."""
>
> epydoc recognizes this (cool!), but displays it with an ellipsis:
>
>    simplifyMapEdges(map, perpendicularDistEpsilon, maxStep=...)
>
> This is not really what I want; can epydoc be modified to display the
> optional
> argument in square brackets like in the docstring?
>
> In case this is relevant, the Python definition is:
>
> def simplifyMapEdges(map, *args):
>     """simplifyMapEdges(map, perpendicularDistEpsilon[, maxStep])

Hello,

you should consider that not everybody has the same conventions to write the
signature. While a certain quantity of heuristics can be applied, i am sure
there will always be a funky example baffling the parser, unless a precise
grammar is specified.

The situation is worse if the signature description is actually different
from what can be introspected: in your latter example a function accepting a
list of positional argument is disguised behind a signature taking two
_named_ parameters, the second of which optional.

A more pythonic way to write your function would be, in my opinion::

    def simplifyMapEdges(map, perpendicularDistEpsilon, maxStep=None):
        """Simplifies all edges in-place.

        :Parameters:
          - `map`: the object to modify
          - `perpendicularDistEpsilon`: you know what it is.
          - `maxStep`: max number of steps. If omitted will be guessed.
        """

There is both a docstring conventions issue and a "pythonic" way to write a
function signature. You may have a good implementation reason to say "*arg"
instead of what i propose: if so, there's noting to be told. But i'd be more
"sincere" in this case and avoid the description of names which are in fact
not used: instead i'd describe in the docstring what the function really
takes as its input and how the caller should invoke. Or else somebody could
try to call your function as "simplifyMapEdges(mymap,
perpendicularDistEpsilon=42)", that will raise an exception.

If forced to keep your signature, i'd write a docstring such::

    def simplifyMapEdges(map, *args):
        """Simplifies all edges in-place.

        :Parameters:
          - `map`: the object to be updated
          - `args`: further positional arguments. At least the first is
            mandatory:

            1. the Perpendicular Distance Epsilon
            2. the max number of steps. If omitted will be guessed.

            Furhter parameters are ignored.
        """

I know that "pythonic conventions" are not the only ones existing, but they
are the most probable in a Python project, so Epydoc is tweaked to do its
best if they are applied and do something in between "what it can" and
"tries to survive" in all the other ones :)

I think you will obtain the best results avoiding to repeat yourself (adding
a signature where it can be introspected instead) and adding descriptions
really matching the "real situation" (which is also useful to detect
errors).

About a point you have raised somewhere else: when a docstring is more than
a paragraph long, only the first is printed in the summary table, while the
complete docstring content is put in a box below. You may found this, and
other useful hints, in the fine manual (tm) ;)

Regards :)

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Am Freitag, 11. Mai 2007 15:52:27 schrieb Daniele Varrazzo:
> About a point you have raised somewhere else: when a docstring is more than
> a paragraph long, only the first is printed in the summary table, while the
> complete docstring content is put in a box below. You may found this, and
> other useful hints, in the fine manual (tm) ;)

I know that (also from e.g. javadoc, Doxygen), and like it.

What I wanted to say is that I have found several examples where the latter 
(the complete docstring) is missing.  I.e. in the summary the first sentence 
is given, but it is *not* a link, and there is nothing to be linked to.  In 
the last mail I attached a simple test case that fails with epydoc-3.0beta1, 
and I just found another one:

def parseGeometry(geometryString):
	"""Convenience function for parsing geometry strings of various
	formats::

	  >>> fig.parseGeometry("320,240-640,480")
	  fig.Rect(320,240,640,480)
	  >>> fig.parseGeometry("50,50+50,50")
	  fig.Rect(50,50,100,100)
	  >>> fig.parseGeometry("40,40,320,240")
	  fig.Rect(40,40,320,240)
	  >>> r = fig.Rect(0,0,320,240)
	  >>> fig.parseGeometry(str(r)) == r
	  True
	"""
	ma = _re_geometry.match(geometryString)

These docs are not listed in the "function details" section either. :-(

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing II: Links between functions, argument highlighting?

[Hans M. <me...@in...>]

Hi again!

Am Freitag, 11. Mai 2007 14:08:37 schrieben Sie:
> On May 11, 2007, at 7:54 AM, Hans Meine wrote:
> > I would expect this to be a FAQ, but I could not find any evidence
> > that epydoc
> > supports automatic cross-referencing of function names?  It would
> > be cool if
> > refererences within docstrings to other functions or to function
> > arguments
> > were recognized and treated specially.
>
> Crossreferences must be made explicitly, but the markup is pretty
> light.  For rst, `foo` or `foo()` or `Foo.foo` etc. (i.e., use
> backticks).

Ah, great, thanks.  That's what I was looking for (maybe put into the FAQ?), 
and I even used the rst syntax in several places for arguments, but I did not 
come across a working example.  That said, what happens here - the docstring 
seems to be truncated (after the first sentence, there is not detailed doc 
extracted)?!

class Face(object):
	def contour(self, index = 0):
		"""face.contour(index)
		
		Returns the index'th contour (same as
		``face.contours()[index]``, but more convenient).
		`index` defaults to 0, which is the exterior contour
		(except for Face 0, the infinite face)."""
		
		return self._anchors[index].clone()

See the attached code, make docs with

   epydoc -v --docformat restructuredtext epydoctest2

Is this a bug in the beta version?

Ciao, /  /
     /--/
    /  / ANS

PS: It would be more convenient if ~"always reply to list" was activated in 
the mailman options.

Re: [Epydoc-devel] =?utf-8?q?Docstring_parsing_II=3A_Links_between_fu?= =?utf-8?q?nctions=2Cargument_highlighting=3F?=

[Daniele V. <pi...@de...>]

On Fri, 11 May 2007 13:54:56 +0200, Hans Meine <me...@in...> wrote:

> Hi!

> 

> I would expect this to be a FAQ, but I could not find any evidence that

> epydoc

> supports automatic cross-referencing of function names?  It would be cool

> if

> refererences within docstrings to other functions or to function arguments

> were recognized and treated specially.



Cross linking is supported with the "L{name}" syntax in epytext docformat and with the default interpreted text role "`name`" in reST docformat. The reference produces a link in HTML output.



Do you mean by "automatic" that every word matching a function/class/variable name should automatically become a link? This would be ambiguous, at best, and woud produce a lot of wrong links.



-- 

Daniele Varrazzo - Develer S.r.l.

http://www.develer.com

Re: [Epydoc-devel] Docstring parsing II: Links between functions, argument highlighting?

[Edward L. <ed...@gr...>]

On May 11, 2007, at 7:54 AM, Hans Meine wrote:
> I would expect this to be a FAQ, but I could not find any evidence  
> that epydoc
> supports automatic cross-referencing of function names?  It would  
> be cool if
> refererences within docstrings to other functions or to function  
> arguments
> were recognized and treated specially.

Crossreferences must be made explicitly, but the markup is pretty  
light.  For rst, `foo` or `foo()` or `Foo.foo` etc. (i.e., use  
backticks).  For epytext, X{foo} or X{foo()} etc.  You can also use X 
{foo<fully-qualified-name>} or `foo<fully-qualified-name>` to give  
short text in the output (foo) for an object that's not locally  
defined or imported.

I chose to use explicit markup, because often function, object, &  
classes have names that are English words; and I didn't want  
crossreference links created in inappropriate places.

-Edward

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi again!

Am Donnerstag, 10. Mai 2007 20:57:17 schrieben Sie:
> Also notice that the PEP 275 discourages to duplicate the function
> signature in the docstring for pure Python modules: it can be retrieved by
> introspection.

That is interesting, I did not know that it was discouraged, but that makes 
sense indeed.

> > c) (enhancement proposal) Finally, I would like to be able to specify
> > several
> > signatures for the same function.  Sometimes, it is possible to call a
> > function with different types of objects / different keyword arguments /
> > ...,
> > and I would like to document two different kinds of use cases.  (Yes,
> > this is
> > a little bit like function overloading, not really pythonic and not very
> > important to me either.)
>
> mmm... this is definitely to be documented in the docstring body. Python
> doesn't support methods overloading: i don't think Epydoc should document a
> function "as it were implemented in C++".

I agree.  While I wrote the above, the idea looked less and less like a good 
one to me. ;-)  However, I now changed this docstring for example:

    """simplifyMapEdges(map, perpendicularDistEpsilon)
    simplifyMapEdges(map, perpendicularDistEpsilon, maxStep)

    Changes ..."""

like this to mark the last argument as optional:

    """simplifyMapEdges(map, perpendicularDistEpsilon[, maxStep])
    ..."""

epydoc recognizes this (cool!), but displays it with an ellipsis:

   simplifyMapEdges(map, perpendicularDistEpsilon, maxStep=...)

This is not really what I want; can epydoc be modified to display the optional 
argument in square brackets like in the docstring?

In case this is relevant, the Python definition is:

def simplifyMapEdges(map, *args):
    """simplifyMapEdges(map, perpendicularDistEpsilon[, maxStep])

    Simplifies all edges in-place ..."""
    pass

Ciao, /  /
     /--/
    /  / ANS

[Epydoc-devel] Docstring parsing II: Links between functions, argument highlighting?

[Hans M. <me...@in...>]

Hi!

I would expect this to be a FAQ, but I could not find any evidence that epydoc 
supports automatic cross-referencing of function names?  It would be cool if 
refererences within docstrings to other functions or to function arguments 
were recognized and treated specially.

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Am Freitag, 11. Mai 2007 13:34:01 schrieb Hans Meine:
> Actually, I remember having read that the upcoming boost 1.34.0 has such a
> feature, that is why I asked a student to try that out, but he told me that
> it hadn't.  Still, a quick search brings up this:
>    http://lists.boost.org/Archives/boost/2007/04/120397.php
> ..which tells us that "Boost.Python now automatically appends C++
> signatures to docstrings.".  (Note that "C++ signatures" include full C++
> type specs before the argument names, and may not even contain the names if
> they were not specified..)
>
> I will try that out myself now and report back.

OK, after some struggling with the changed build system, which is incompatible
with our university's NFS layout, I found that it works indeed (no clue why I
was told that it does not work).  Here are some examples:

Function exported without any doc markup:
In [2]: applyFourierFilter.__doc__
Out[2]: 'C++ signature:\n    applyFourierFilter(vigra::PythonFixedBandsImage<float>, vigra::PythonFixedBandsImage<float>) -> vigra::PythonFixedBandsImage<vigra::TinyVector<float, 2> >'

The same, but a method of the class Diff2D:
In [4]: Diff2D.norm.__doc__
Out[4]: 'C++ signature:\n    norm(vigra::Diff2D {lvalue}) -> double'

Function exported with argument names, but no docstring:
In [5]: oversamplingGradient.__doc__
Out[5]: 'C++ signature:\n    oversamplingGradient(vigra::PythonSingleBandImage image, double sigma, bool withOffset=False) -> vigra::PythonFixedBandsImage<vigra::TinyVector<float, 2> >'

Function exported with both docstring (incl. signature) and argument names:
In [6]: susanDiscWindow.__doc__
Out[6]: 'susanDiscWindow(image, threshold, radius = 3.4, similarityExponent = 6.0)\nthreshold: grayvalue similarity threshold\nradius: radius of the circular window (default 3.4 -> 37 pixels)\nsimilarityExponent: exponent of the Gaussian similarity measure\nC++ signature:\n    susanDiscWindow(vigra::PythonImage image, double threshold, double radius=3.3999999999999999, double similarityExponent=6.0) -> vigra::PythonFixedBandsImage<float>'

That is, boost::python indeed *appends* the C++ signature to the docstring,
prepending a unique prefix as you can see.

There is support for switching the signatures off, and one can even disable
all docstrings, but the format seems to be fixed, hard-coded, and parsable:

> docstring_options(bool show_all=true);
>
> Effects: Constructs a docstring_options object which controls the
> appearance of function and member-function docstrings defined in the
> code that follows. If show_all is true, both the user-defined
> docstrings and the automatically generated C++ signatures are
> shown. If show_all is false the __doc__ attributes are None.
>
> docstring_options(bool show_user_defined, bool show_signatures);
>
> Effects: Constructs a docstring_options object which controls the
> appearance of function and member-function docstrings defined in the
> code that follows. Iff show_user_defined is true, the user-defined
> docstrings are shown. Iff show_signatures is true, C++ signatures are
> automatically added. If both show_user_defined and show_signatures are
> false, the __doc__ attributes are None.

Hope that helps.

-- 
Ciao, /  /
     /--/
    /  / ANS