epydoc-devel — Discussions about epydoc development

Re: [Epydoc-devel] introspection misconception

[<oti...@ya...>]

>   % epydoc --introspect-only foo/__init__.py
> [...]
>  __all__ = ['FooBar']

thank you! Exactly what I wanted to know.

> So I'm not sure I see the benefit of deleting 'bar' from the 'foo' namespace.

You are right that in that toy example it doesn't make sense. I am using it
on a much larger module-submodule structure, where I dont' want my
namespaces to be cluttered by filenames (in this example bar.py is just a
file where I want to put some code, not a module that a user should import).

thank you again!

tiziano






      ____________________________________________________________________________________
Never miss a thing.  Make Yahoo your home page. 
http://www.yahoo.com/r/hs

Re: [Epydoc-devel] introspection misconception

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

>  I'm running into a problem using epydoc with introspection,
>  [...]
>  whereas, using 'introspection-only' I was under the impression that I would
>  get docs for
>   foo, foo.FooBar.
>  [...]
>  What am I missing here? [...]

A couple things: first, if you tell epydoc to document a package
directory, it will automatically document every module in that
package, regardless of whether it gets imported by the main module's
__init__.py file.  If you want to tell epydoc to document *just* the
package itself, and not any of the modules inside the package, you
should run epydoc on the __init__.py file, not on the package
directory.  I.e.:

    % epydoc --introspect-only foo/__init__.py

The second thing is that epydoc is generally careful about figuring
out where something is *actually* defined, and documenting it there;
99% of the time, when an object is imported, it's so that it can be
used, not to move it to a different namespace.  So in this case,
epydoc assumes that FooBar is getting imported into the foo module
just to be used, not to modify the API.  To tell epydoc that you want
FooBar to be listed in the foo module explicitly, you'll need to
define the __all__ variable in the foo module.  In your example case,
you would use:

    __all__ = ['FooBar']

If you make those two changes (defining __all__ in foo/__init__.py,
and running epydoc on foo/__init__.py), then you should get the
results you expect.

One final note, though...  Your package as defined has the following
potentially confusing behavior:

>>> import foo.bar
>>> print foo.bar
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'module' object has no attribute 'bar'

Of course, a persistent user can still access the module:

>>> import sys
>>> sys.modules['foo.bar']
<module 'foo.bar' from 'foo/bar.pyc'>

So I'm not sure I see the benefit of deleting 'bar' from the 'foo' namespace.

-Edward

[Epydoc-devel] introspection misconception

[<oti...@ya...>]

Dear epydoc devels, thank you for maintaining epydoc, which is a software
I depend on daily basis :-)))
I'm running into a problem using epydoc with introspection, but I am not
sure if this is a bug, a feature or a misconception on my part. If I have a
python module organized as follows:

foo/
foo/__init__.py
foo/bar.py

where __init__.py consists of the following two lines:
from bar import FooBar
del bar

and bar.py of the following two lines:
class FooBar(object):
    """Nice Class"""
    pass

importing the above module in python shows:
>>> import foo
>>> dir(foo)
['FooBar', '__builtins__', '__doc__', '__file__', '__name__', '__path__']

which, as expected, shows the class 'FooBar' as the only non-private 
member of module 'foo' . If I now generate the API docs with epydoc using 
'parse-only' I get documentation for:
 foo, foo.bar, foo.bar.FooBar
whereas, using 'introspection-only' I was under the impression that I would
get docs for
 foo, foo.FooBar.
What happens instead is that for 'introspection-only', docs are generated 
for
 foo, foo.bar', foo.bar'.FooBar
with a warning that a variable shadows the module 'bar'. 

What am I missing here? I thought introspection meant that epydoc is
importing my module and introspecting it to find out all its members. But
with introspection only, one would never get to "foo.bar", which is not
available in the namespace of "foo". 
I am sorry if the question sounds odd, but  that's probably because I did
not understand how epydoc assigns names to objects. 
I'm attaching for convenience a tarball with the python modules and
the docs generated by epydoc with parsing and introspection.

thank you!

tiziano






      ____________________________________________________________________________________
Looking for last minute shopping deals?  
Find them fast with Yahoo! Search.  http://tools.search.yahoo.com/newsearch/category.php?category=shopping

Re: [Epydoc-devel] How to use custom images?

[Daniele V. <dan...@gm...>]

Manuel ha scritto:
> Thanks.
> But unfortunately it not work here (I'm working with Windows)...

There is no problem with docutils on windows: it is a pure Python module. Of 
course you have to install the docutils package (from 
http://docutils.sourceforge.net)

There are two glitches in your example:

1. the __docformat__ must be a module variable, not a class variable;

2. in reST syntax you need a blank line above the directives (i.e. image).

Below the fixed example, which works as expected.

     __docformat__ = 'restructuredtext'

     def foo():

          """
          Here's an image:

          .. image:: img_04.png
          """
          pass

Regards,

-- Daniele

Re: [Epydoc-devel] How to use custom images?

[Manuel <in...@ma...>]

Thanks.
But unfortunately it not work here (I'm working with Windows)...

I've uploaded the test:

http://www.makehuman.org/tmp/epydoc_test.zip

The result has not img tags:

---------------------
   <table width="100%" cellpadding="0" cellspacing="0" border="0">
   <tr valign="top"><td>
   <h3 class="epydoc"><span class="sig"><span 
class="sig-name">foo</span>()</span>
   </h3>
   </td><td align="right" valign="top"
     ><span class="codelink"><a 
href="foo-pysrc.html#foo">source&nbsp;code</a></span>&nbsp;

     </td>
   </tr></table>

   <p>Here's an image: .. image:: img_04.png</p>
   <dl class="fields">
   </dl>
</td></tr></table>
-------------------------

Maybe it's my error.
Anyway no warning from epydoc console.
Can you take a look?

Regards,

          Manuel

PS:: the image is not in the zip, but for me it's sufficient to see
a generated img tag...



Edward Loper ha scritto:
>> Hi!
>  >  Just a quick question.
>  >  It's possible to use custom images to improve documentation, in example png?
> 
>  It's possible if you use reStructuredText as your markup language,
>  using the "..image::" directive.  But epydoc doesn't currently copy
>  the image into the target directory, so you'll have to do that
>  yourself.  A simple example:
> 
>  --------- start of foo.py -----------
>  """
>  Here's an image:
> 
>  .. image:: face.png
>  """
>  __docformat__ = 'restructuredtext'
>  --------- end of foo.py -----------
> 
>  And then you'd need to copy "face.png" into the output directory where
>  epydoc wrote its files.  Alternatively, you could do something like:
> 
>  --------- start of foo.py -----------
>  """
>  Here's an image:
> 
>  .. image:: ../images/face.png
>  """
>  __docformat__ = 'restructuredtext'
>  --------- end of foo.py -----------
> 
>  Assuming that there will be a directory 'images' that is a sister to
>  the directory where epydoc writes its output.
> 
>  -Edward
> 
> -------------------------------------------------------------------------
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2008.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
> _______________________________________________
> Epydoc-devel mailing list
> Epy...@li...
> https://lists.sourceforge.net/lists/listinfo/epydoc-devel
> 
> 
> 

Re: [Epydoc-devel] How to use custom images?

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

> Hi!
 >  Just a quick question.
 >  It's possible to use custom images to improve documentation, in example png?

 It's possible if you use reStructuredText as your markup language,
 using the "..image::" directive.  But epydoc doesn't currently copy
 the image into the target directory, so you'll have to do that
 yourself.  A simple example:

 --------- start of foo.py -----------
 """
 Here's an image:

 .. image:: face.png
 """
 __docformat__ = 'restructuredtext'
 --------- end of foo.py -----------

 And then you'd need to copy "face.png" into the output directory where
 epydoc wrote its files.  Alternatively, you could do something like:

 --------- start of foo.py -----------
 """
 Here's an image:

 .. image:: ../images/face.png
 """
 __docformat__ = 'restructuredtext'
 --------- end of foo.py -----------

 Assuming that there will be a directory 'images' that is a sister to
 the directory where epydoc writes its output.

 -Edward

[Epydoc-devel] How to use custom images?

[Manuel <man...@ti...>]

Hi!
Just a quick question.
It's possible to use custom images to improve documentation, in example png?
Thanks,

         Manuel

Re: [Epydoc-devel] Documentation not associated with a particular module, function, class, or method

[Joseph T. <tu...@gm...>]

> Epytext instead has a nice feature that may help you: indexed terms:
>
> http://epydoc.sourceforge.net/manual-epytext.html#indexed-terms
>
> You can define a graph in a module docstring and refer to it even without
> creating dummy python objects.
>

Thanks for the suggestions. Unfortunately, I already tried indexed terms and
they don't work. In particular, I cannot L{graph} to link to the indexed
term.

Any more ideas? Or is this a genuine new feature that needs to be
implemented?

Thanks,
   Joseph

-- 
Academic: http://www-etud.iro.umontreal.ca/~turian/
Business: http://www.metaoptimize.com/

Re: [Epydoc-devel] Documentation not associated with a particular module, function, class, or method

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

Joseph Turian ha scritto:
> Daniele,
> 
> I did consider it, but I am not sure if it solves our usage requirements.
> Maybe you can help?
>  
> [...]
> Okay. But how do I create a standalone document about the "graph" 
> concept and then, within the code main code, link to the "graph" concept 
> using @see or L{graph}? This is what I couldn't figure out.

Mmm... no, you are right. Currently i don't think there is a way to reference 
external documentation if not with a full url.

Epytext instead has a nice feature that may help you: indexed terms:

http://epydoc.sourceforge.net/manual-epytext.html#indexed-terms

You can define a graph in a module docstring and refer to it even without 
creating dummy python objects.

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

Re: [Epydoc-devel] Documentation not associated with a particular module, function, class, or method

[Joseph T. <tu...@gm...>]

Daniele,

Have you considered the use of reStructuredText syntax to produce your
> documentation?


I did consider it, but I am not sure if it solves our usage requirements.
Maybe you can help?


> Just like epytext it can be used to produce API documentation
> with Epydoc, but it is already geared towards the production of standalone
> documents too (with titles, ToC, metadata etc.) and is ready to produce
> html,
> pdf and some other fancy format.


Okay. But how do I create a standalone document about the "graph" concept
and then, within the code main code, link to the "graph" concept using @see
or L{graph}? This is what I couldn't figure out.


Epydoc also contains a script - apirst2html.py - allowing a standalone reST
> document to reference API docs generated with Epydoc itself, e.g. citing
> :api:`some_function()` or :api:`module.Class`. The script converts the
> document into HTML and links the objects marked with the above syntax to
> the
> matching epydoc-generated API docs.


What about linking from epydoc comments to the standalone reST? Is there a
clean approach (not just hardcoding an external URL)?

Thanks,
  Joseph

-- 
Academic: http://www-etud.iro.umontreal.ca/~turian/
Business: http://www.metaoptimize.com/

Re: [Epydoc-devel] Documentation not associated with a particular module, function, class, or method

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

Joseph Turian ha scritto:
> I am understanding someone else's code, and helping to document it as I 
> understand it.
> The author was explaining to me and using the term "graph". Graph is not 
> actually a particular module, function, class, or method.
> It is just an umbrella concept tying together a lot of things.
> 
> We are trying to write documentation for the "graph" concept.
> We would prefer to write it using epytext markup (as opposed to 
> independent HTML documentation) so that links to epydoc-generated HTML 
> is created.

Have you considered the use of reStructuredText syntax to produce your 
documentation? Just like epytext it can be used to produce API documentation 
with Epydoc, but it is already geared towards the production of standalone 
documents too (with titles, ToC, metadata etc.) and is ready to produce html, 
pdf and some other fancy format.

Epydoc also contains a script - apirst2html.py - allowing a standalone reST 
document to reference API docs generated with Epydoc itself, e.g. citing 
:api:`some_function()` or :api:`module.Class`. The script converts the 
document into HTML and links the objects marked with the above syntax to the 
matching epydoc-generated API docs.

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

Re: [Epydoc-devel] Documentation not associated with a particular module, function, class, or method

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

If you just want to convert stand-alone epytext to html, it's not too
hard.  But if you want it to include links into the documentation
generated by epydoc, then things get a bit trickier.

The code following this email should do basically what you want -- it
runs the epydoc command line interface (with options taken from
sys.argv), and then has some code at the end to parse a text file
containing epytext material (linking it to the docs), and write it as
html to the output directory.  It's a bit hackish, though, I'm afraid.

A better solution would probably be to add the ability for epydoc to
read files containing epytext (or rst) and convert them natively..
something like:

  % epydoc my_package/ --rst-file my_docfile.rst --epytext-file
my_other_docfile.txt

Some issues might have to be worked out though, such as what files
they would be written to in the output, whether they could get
referenced by docstrings in python code, etc.

-Edward

========================================================

import epydoc.cli, os.path
from epydoc.markup.epytext import ParsedEpytextDocstring, pparse
from epydoc.docwriter.html import HTMLWriter

# Run epydoc.
options = epydoc.cli.parse_arguments()
docindex = epydoc.cli.main(options)
html_writer = HTMLWriter(docindex, **options.__dict__)
html_writer._directory = options.target['html']

TEMPLATE = "<html><head>Hello</head><body>%s</body></html>"

# Convert my own file.
doc = ParsedEpytextDocstring(pparse(open('foo.txt').read()))
out = open(os.path.join(options.target['html'], 'foo.html'), 'w')
out.write(TEMPLATE % html_writer.docstring_to_html(doc))
out.close()

Re: [Epydoc-devel] Documentation not associated with a particular module, function, class, or method

[Joseph T. <tu...@gm...>]

I guess I was thinking something along the lines of the Doxygen \page
command:
   http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpage
" Indicates that a comment block contains a piece of documentation that is
not directly related to one specific class, file or member. The HTML
generator creates a page containing the documentation. The [image:
$\mbox{\LaTeX}$] generator starts a new section in the chapter `Page
documentation'."


If you just want to convert stand-alone epytext to html, it's not too
> hard.  But if you want it to include links into the documentation
> generated by epydoc, then things get a bit trickier.


Yeah, I wanted the tricky thing :^)

The code following this email should do basically what you want -- it
> runs the epydoc command line interface (with options taken from
> sys.argv), and then has some code at the end to parse a text file
> containing epytext material (linking it to the docs), and write it as
> html to the output directory.  It's a bit hackish, though, I'm afraid.


I wasn't able to figure out how to invoke this code.
Does it provide links to and from graph? That's what I need.

A better solution would probably be to add the ability for epydoc to
> read files containing epytext (or rst) and convert them natively..
> something like:
>
>  % epydoc my_package/ --rst-file my_docfile.rst --epytext-file
> my_other_docfile.txt


That sounds great.
Ideally, I could do: --epytext-file extra/*.txt

Some issues might have to be worked out though, such as what files
> they would be written to in the output, whether they could get
> referenced by docstrings in python code, etc.


Instead of -module  -pysrc or -class, just use -page (as does doxygen).
They should definitely be able to reference and be referenced by docstrings
in the python code.
The idea for "page" is to be able to describe general concepts and design
decisions, and link to them in docstrings as needed.

Thanks,
   Joseph

-- 
Academic: http://www-etud.iro.umontreal.ca/~turian/
Business: http://www.metaoptimize.com/

Re: [Epydoc-devel] RE dot png option

[Joseph T. <tu...@gm...>]

Okay.

I just tried working with the SVN head, but have the following error during
'python setup.py install':

byte-compiling
/usr/lib/python2.5/site-packages/epydoc/markup/restructuredtext.py to
restructuredtext.pyc
  File "/usr/lib/python2.5/site-packages/epydoc/markup/restructuredtext.py",
line 605
    raise SkipNode()
        ^
SyntaxError: invalid syntax



On Tue, Feb 26, 2008 at 7:04 PM, Edward Loper <ed...@se...>
wrote:

> On Tue, Feb 26, 2008 at 6:44 PM, Joseph Turian <tu...@gm...> wrote:
> > > dot shipped with fedora doesn't support gif output. Can we add an
> option
> > to
> > > select png? (IMHO, this should be the default anyway)
>
> The subversion head (revision 1800) now supports the
> "--graph-image-format" option (and config file variable), whose values
> can currently be "png," "gif," or "jpg."  I'd like to do more
> investigation before I change the default format to png -- I seem to
> remember some older versions of dot not supporting it.
>
> -Edward
>



-- 
Academic: http://www-etud.iro.umontreal.ca/~turian/
Business: http://www.metaoptimize.com/

Re: [Epydoc-devel] RE dot png option

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

On Tue, Feb 26, 2008 at 6:44 PM, Joseph Turian <tu...@gm...> wrote:
> > dot shipped with fedora doesn't support gif output. Can we add an option
> to
> > select png? (IMHO, this should be the default anyway)

The subversion head (revision 1800) now supports the
"--graph-image-format" option (and config file variable), whose values
can currently be "png," "gif," or "jpg."  I'd like to do more
investigation before I change the default format to png -- I seem to
remember some older versions of dot not supporting it.

-Edward

[Epydoc-devel] Documentation not associated with a particular module, function, class, or method

[Joseph T. <tu...@gm...>]

I am understanding someone else's code, and helping to document it as I
understand it.
The author was explaining to me and using the term "graph". Graph is not
actually a particular module, function, class, or method.
It is just an umbrella concept tying together a lot of things.

We are trying to write documentation for the "graph" concept.
We would prefer to write it using epytext markup (as opposed to independent
HTML documentation) so that links to epydoc-generated HTML is created.

What is the best way to do this?
Do I have to make a dummy documentation module graph.py, or is there a more
elegant approach?

Thanks,
  Joseph


-- 
Academic: http://www-etud.iro.umontreal.ca/~turian/
Business: http://www.metaoptimize.com/

[Epydoc-devel] RE dot png option

[Joseph T. <tu...@gm...>]

> dot shipped with fedora doesn't support gif output. Can we add an option
to
> select png? (IMHO, this should be the default anyway)

I second Neal's suggestion. We don't have PNG on our end either.

-- 
Academic: http://www-etud.iro.umontreal.ca/~turian/
Business: http://www.metaoptimize.com/

Re: [Epydoc-devel] latex output

[Jonathan G. <gu...@ni...>]

On Feb 19, 2008, at 7:47 PM, Edward Loper wrote:

> On Feb 19, 2008 6:17 PM, "Jürgen Waser" <Jue...@gm...> wrote:
>> I have a 2 questions regarding output to LATEX:
>
> The latex writer is not as fully developed as I would like -- if
> anyone wants to volunteer to work on it, I'd be happy to provide
> support. :)

I offered a substantial patch awhile back. I guess it slipped through  
the cracks?

Here's the link: http://www.matforge.org/fipy/wiki/EpydocLaTeX

Re: [Epydoc-devel] latex output

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

On Feb 19, 2008 6:17 PM, "Jürgen Waser" <Jue...@gm...> wrote:
> I have a 2 questions regarding output to LATEX:

The latex writer is not as fully developed as I would like -- if
anyone wants to volunteer to work on it, I'd be happy to provide
support. :)

> 1. There are no private methods listed in my output, even though I get them
> when exporting to HTML. Am I doing something wrong? Is it working for anybody
> else?

It looks to me like applying the following change to
epydoc/docwriter/latex.py should do the right thing:

===================================================================
--- docwriter/latex.py	(revision 1727)
+++ docwriter/latex.py	(working copy)
@@ -128,7 +128,7 @@
     def __init__(self, docindex, **kwargs):
         self.docindex = docindex
         # Process keyword arguments
-        self._show_private = kwargs.get('private', 0)
+        self._show_private = kwargs.get('show_private', 0)
         self._prj_name = kwargs.get('prj_name', None) or 'API Documentation'
         self._crossref = kwargs.get('crossref', 1)
         self._index = kwargs.get('index', 1)

> 2. Is there an option to omit the documentation of base classes at all?
> (I don't want to show any inherited elements)

Not currently, but it wouldn't be that hard to add.  The 'listed'
inheritance mode is too verbose for your code base?  Suggested name
for this inheritance mode, to go along with 'listed' and 'grouped' and
'included'?  Perhaps 'hidden' or 'skipped'?

-Edward

[Epydoc-devel] latex output

[Jürgen W. <Jue...@gm...>]

I have a 2 questions regarding output to LATEX:

1. There are no private methods listed in my output, even though I get them
when exporting to HTML. Am I doing something wrong? Is it working for anybody
else?

2. Is there an option to omit the documentation of base classes at all?
(I don't want to show any inherited elements)

Thanks for any help,
Jurgen


-- 
GMX startet ShortView.de. Hier findest Du Leute mit Deinen Interessen!
Jetzt dabei sein: http://www.shortview.de/?mc=sv_ext_mf@gmx

Re: [Epydoc-devel] Epytext markup enhancement suggestions

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

> Here is another suggestion which we might have not discussed before.
>
> @param int x: This is a description of  x
> @param MyClass x: This is a description of x
> @param int or string x: This is a description of x
> @return int x: This is a description of type

The "@return" example doesn't make sense to me -- there's no variable
name associated with a return value.

For the "@param" examples -- I understand that this ordering has a
long history, and is very familiar from statically typed languages.
Nevertheless, I still find myself reluctant to add it.  Let's add the
postfix parenthesized form (i.e., "@param x (int): descr", try it out
for a while, and then you can tell me if you think this prefix form is
still necessary.  To quote the Zen of Python again, "There should be
one -- and preferably only one -- obvious way to do it."

> I agree. However, due to all statically typed languages out there, people
> have used to have int before their x.

I can see how the difference between having a colon and not could trip
people up -- the circumstances of using @param in other languages and
@param in epydoc is very similar.  But this (prefixed types) is more a
case of something that might be familiar to users, not something that
might trip them up.

> > on the topic of creating a formal language for expressing types: [...]
>
> A very good point. How about
>
> @param list x: The description of x.
> @param list(int) x: The description of x
> @param dict(str, MyClass) x: The description of x
> @param tuple(int) x: The description of x

You're free to use this homegrown type specification language yourself
-- epydoc will render them just as you type them, and it will be up to
your documentation readers to interpret them.  But I don't want to
make it (or any other non-standard type specification language) part
of epydoc itself.  So, as I said before, unless Python adopts a
standard type specification language (which seems unlikely to me),
epydoc won't support one.

-Edward

Re: [Epydoc-devel] Epytext markup enhancement suggestions

[Mikko O. <mi...@re...>]

Hello all,

Epydoc expects to find a *single* description of the type of a
> parameter.  I.e., the correct way to write that is:
>
>     @param x: blah
>     @type x: None or str


Ah,  my bad then =)


> > I have strong point to make here. This could be a taste issue. There is
> no
> > official "comment document standard", but no other language uses :
>
>
> Some markup languages that use ":" as a field separator:
>   - rfc822-style headers (very widely used, eg by email)
>   - restructuredtext


That's true. The point I was trying highlight is that other programming
languages and comment documentation systems do @param without :. I want to
make it easy for people migrating from other languages - Python is catching
more and more fire every day (the programming language of 2007 and so on).
When I started to document my code with Epytext, which is the easiest
documentation tool available for Python currently, I found this : issue very
frustrating, since my previous habits tend to make me type @param without :.

@group Group Name: x, y, z
> @var x, y, z: Description of several variables at once
> @param x, y, z: Description of several parameters at once
>
> These would not be possible if there was no colon.


True. I am not suggesting ditching @xxx y: syntax completely. I just hope it
could be left out from the simplest cases which I belive 80% of
documentation lines are. The ultimate goal is to streamline the grunt work
and have big cannons available for hard cases =)

Epytext already detects the case where you have a line that starts
> with "@" but there's no corresponding ":" -- and it flags it as a
> warning.


Trust me, I have seen a lot of these warnings =)


> So I guess I might be ok with making the ":" optional.  That way,
> things like "@group Group Name: x, y, z" would continue to work, but
> things like "@param x description" would also work.  The following
> case might trip people up sometimes:
>
>     @param x this is a description of x.  Read about: y
>
> where there's a ":" further along in the first line (after "Read
> about").  But I guess that would be fairly rare, and epydoc should be
> able to complain in that case.


You are righ. This would also fall into "special cases" which probably don't
appear that often.


So, given all that, my counterproposal
> is for epytext to understand the following syntaxes:




@param x: This is a description of x.
> @param x This is a description of x.
> @param x (int) This is a description of x.
> @param x, y, z: A description of three variables
> @group Name of Group: x, y, z
> @group Transformers x, y, z
> @return int: This is a description of the return value.
> @return This is a description of the return value.
> @return: This is a description of the return value.


Here is another suggestion which we might have not discussed before.

@param x (int): This is a description of x.

-->

@param int x: This is a description of  x
@param MyClass x: This is a description of x
@param int or string x: This is a description of x
@return int x: This is a description of type


Parameter type rule: If there are several words before the colon of @param
line, threat the last word as a parameter name and the former words as a
type description. This resembles more C-like syntax which is widely
recognized and I believe Javascript (Ext JS) does this. In PHP
documentation, another languague having dynamic types, the syntax would be:

@param int $x This is a description of x. Since Python doesn't (luckily)
have $ notitation, $ wouldn't fit well.


So the ":" is required for:
>   - @return with type
>   - @param w/ multiple vars


Right. But let's consider above "type definition" notation for @return and
@param.

And optional in all other case.


Backwards compability++ :)


> I don't like having types be prefixed -- it makes
> it too hard to scan for the name of the param,


Consider above type definition example with colon. I find it quite readable,
since parameter name is always left from the colon. Some perfectionist could
add some whitespaces to align all parameter names into a column.

which is much more
> important than the type.  More important information should come
> before less important information.)  Return types are specified as an
> argument to the field.


I agree. However, due to all statically typed languages out there, people
have used to have int before their x.


Of course, there are some issues with this proposal, and the way
> markup languages are currently set up.  One is that there is currently
> a very strong abstraction barrier between epytext and epydoc --
> epytext defines a markup syntax for field lists, but has nothing to
> say about what fields can be used, or what their meanings are.  In
> order to allow some fields (like @param) to automatically eat the
> first following word as an argument, while others (like @summary)
> don't, will require that abstraction barrier to be weakened -- epytext
> will need to know what fields are expected, and what to do with them.


I haven't yet checked how epytext and epydoc play together - I have only
experience hacking Doxygen. I believe the problem could be solved by adding
"postprocess" step when the documentation is compiled: all type information
is out there to exploit. It could go through @param definitions and do the
magic - users love magic as an alternative for hand-typing!


> So what do you think of this proposal?


I think it's heading to the right way when pursuing my goal of having better
compatibility with other documentation languages.

p.s., on the topic of creating a formal language for expressing types:
> unless Python defines a standard formal language for types, I'm
> strongly opposed to coming up with our own.  "Explicit is better than
> implicit" is the second rule in the zen of python. :)  Your suggested
> format:
>
>     @param [int] x description...
>
> Makes me think x is an integer, not a list of ints.  Also, note that
> Python is a language with a strong culture of duck typing, and precise
> notions of type are often not applicable.


A very good point. How about

@param list x: The description of x.

Since Python lists (tuples, dicts) are generic types, the documentation does
not "want to tell" what's inside the list.

..or...

@param list(int) x: The description of x

and

@param dict(str, MyClass) x: The description of x
@param tuple(int) x: The description of x

These resemble the Python syntax somehow. Collection-like return types are
an issue which could be discussed through too!


-- 
Mikko Ohtamaa
www.redinnovation.com
Every problem is solvable if you can throw enough energy drinks at it

[Epydoc-devel] Fwd: Epytext markup enhancement suggestions

[Mikko O. <mi...@re...>]

I had accidentally posted this to Edward when I was going to post to the
list.

---------- Forwarded message ----------
From: Mikko Ohtamaa <mi...@re...>
Date: 15.2.2008 21:36
Subject: Re: [Epydoc-devel] Epytext markup enhancement suggestions
To: Edward Loper <ed...@se...>

Hi all,

Thank you for great feedback. It's nice to see discussion which could lead
to the evolution of open source tools :)

>
> > 1. Leave out : (other languages don't use it either)
>
>
> I'm actually fairly partial to that ": myself -- to my eyes, your
> examples are hard to read because I don't know where the field body
> begins.  E.g. in your proposed:
>

I have strong point to make here. This could be a taste issue. There is no
official "comment document standard", but no other language uses :

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html
http://java.sun.com/j2se/javadoc/writingdoccomments/#tag
C# uses XML tags
Doxygen does not have : in Java-like mode:
http://www.stack.nl/~dimitri/doxygen/docblocks.html<http://www.stack.nl/%7Edimitri/doxygen/docblocks.html>.
In non-Java mode Doxygen uses \param.

I wish that we would make learning curve for people coming for other
languages as low as possible. Personally, I was wondering. why epytext
didn't work for my @param tags until I noticed the important :.


@param int|str a parameter description here
>
>
> I have a strong tendency to read "a" as an indefinite article, not a
> variable name.


Sorry, I am not native English speaker and Finnish lacks articles :)

Also, note that the "type description" doesn't have to
> be a single word, or even a simple expression.  I want people to be
> able to express such notions as "dictionary from int to string" or
> "sequence of int" or "nonnegative int," and human language is a great
> way to do it. :)


If we have formal way to define syntax, we can automatically link type
definition to the correct type. Also, there is the longer description
"parameter description here" for special cases. The point is to avoid extra
@type definition which would lead to extra line of typing from the
developer. Also, typing C{}... something around a class definition is a
habit of epytext only and other document comments avoid this somehow.

Few more examples

def ban(usernames):
  """
  @param [string] usernames  A sequence of usernames who will be banned
  """

[] could mark dict, list and tuple. Or

def  ban(users):
    """
    @param [mooware.models.User] A tuple of User objects
    """"



And finally, including the ":" explicitly allows us
> to implement your suggestion (2) as an optional feature -- we don't
> want all the docstrings people have already written suddenly and
> mysteriously breaking when they upgrade epydoc!


I 100% agree. I don't want to break backwards compatibility. If we cannot
make a parser which automatically detects these cases, I recommend that

- I can create a dialect which is a chose of the developer (__doctring__ =
"epytext-java")

- A command-line switch



> > 3. Use | to separate different possible types
>
>
> I'm not sure what you intend for the behavior to be here.  You can
> already write "int|str", and it will be rendered as such in your
> output.  Do you want the "|" to get translated to "or" in the output?
> If not, why not just write "int or str"?


The point is that when parameter/return types are formally defined, so the
parser can link it to the specific class. | is a way to define multiple
return types on a single line. It really does not matter for me whether it
would be | or "or". I just picked | because PHP was already using it. But
after receving your feedback, it became obvious this is very non-pythonic
and "or" should be used :)

This could be a usual case

def find_foo(id):
  """
  @return Foo|None Return Foo instance or None if id is not found
 """

istead of

def find_foo(id)
   """
   @return: Foo instance or None if id is not found
   @rtype Foo
   @rtype None
"""
   """

So with this modified proposal (keep ":", allow types as prefix
> strings, and just use "or"), your example function would be:
>
> def f(a, b):
>     """
>     @param int or str a: parameter description here
>
>     @param module.Class b: parameter description here
>
>     @return float: return value description here
>     """"
>
> An open question is how the "type prefix" string would interact with
> epydoc's current support for having a single "@param" that describes
> multiple parameters.  E.g.:
>
> @def f(x, y):
>     """
>     @param x, y: The coordinates of some point.
>     """
>
> We wouldn't want "x," being interpreted as a type for y!  This would
> be one advantage of a syntax like "@param x (int): ..." that more
> explicitly marks the type expression.


With the new syntax this could be

def f(x,y)
   """
   @param x or y The coordinates of somepoint
   """

Well again... I think | was useful after all, since you can concatenate all
return types to a single word (no spaces) and parsing compatibility could
not be achieved. It would be impossible to parse @param xory The
coordines... :)

Anyways I think we are on a right track to get rid of @type and @rtype and I
could help to implement some of these solutions (if not all).

Cheers,
Mikko


-Edward
>



-

Re: [Epydoc-devel] Epytext markup enhancement suggestions

[Huu Da T. <huu...@gm...>]

Edward Loper wrote:

>> 2. Leave out @type, @rtype and describe type inline as the first word of
>> parameter paragraph.
> 
> I wouldn't mind adding some syntax that would allow types to be
> optionally specified as part of a parameter/returns field.  With your
> proposal this would look like (keeping the ":" because I like it):
> 
> @param int x: the x coordinate
> 
> I also wouldn't mind any number of alternatives, including:
> 
> @param x (int): the x coordiante
> @param x [int]: the x coordinate

I like the () option as it looks like cast. It is a great idea for 
simple type, but when extending it complex type (or with formatting), I 
believe it would be hard to read. How would this be translated into the 
suggested format?

@param var1: first param.
@type var1: C{int} | C{None}
@param var2: an object
@type var2: L{search<re.search>}


-- 
Huu Da Tran <huu...@gm...>
Fidèle esclave des félins

Qui m'insulte, parfois, me dit la vérité.
Qui me flatte, plus souvent qu'autrement, me ment!

Re: [Epydoc-devel] Epytext markup enhancement suggestions

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

> Epydoc is the best thing since the sliced bread happened for Python [...]

Thanks! :)

> I have been wondering if it where possible to make epytext markup even
> simpler. [...]

> 1. Leave out : (other languages don't use it either)

I'm actually fairly partial to that ": myself -- to my eyes, your
examples are hard to read because I don't know where the field body
begins.  E.g. in your proposed:

@param int|str a parameter description here

I have a strong tendency to read "a" as an indefinite article, not a
variable name.  Also, note that the "type description" doesn't have to
be a single word, or even a simple expression.  I want people to be
able to express such notions as "dictionary from int to string" or
"sequence of int" or "nonnegative int," and human language is a great
way to do it. :)  And finally, including the ":" explicitly allows us
to implement your suggestion (2) as an optional feature -- we don't
want all the docstrings people have already written suddenly and
mysteriously breaking when they upgrade epydoc!

> 2. Leave out @type, @rtype and describe type inline as the first word of
> parameter paragraph.

I wouldn't mind adding some syntax that would allow types to be
optionally specified as part of a parameter/returns field.  With your
proposal this would look like (keeping the ":" because I like it):

@param int x: the x coordinate

I also wouldn't mind any number of alternatives, including:

@param x (int): the x coordiante
@param x [int]: the x coordinate

> 3. Use | to separate different possible types

I'm not sure what you intend for the behavior to be here.  You can
already write "int|str", and it will be rendered as such in your
output.  Do you want the "|" to get translated to "or" in the output?
If not, why not just write "int or str"?

So with this modified proposal (keep ":", allow types as prefix
strings, and just use "or"), your example function would be:

def f(a, b):
    """
    @param int or str a: parameter description here
    @param module.Class b: parameter description here
    @return float: return value description here
    """"

An open question is how the "type prefix" string would interact with
epydoc's current support for having a single "@param" that describes
multiple parameters.  E.g.:

@def f(x, y):
    """
    @param x, y: The coordinates of some point.
    """

We wouldn't want "x," being interpreted as a type for y!  This would
be one advantage of a syntax like "@param x (int): ..." that more
explicitly marks the type expression.

-Edward