epydoc-devel — Discussions about epydoc development

[Epydoc-devel] Epytext markup enhancement suggestions

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

Hi all,

Epydoc is the best thing since the sliced bread happened for Python which
otherwise lacks naming conventions and such. The goal of documentation is to
make the process simple as possible, so that it wouldn't "hinder" the work
of development and that's what Epydoc does well.

I have been wondering if it where possible to make epytext markup even
simpler. Based on my experiences in PHP and Java formal comment blocks, here
are some suggestions:

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

Versus (old style)

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

I see a consirably win =)

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

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

3. Use | to separate different possible types

These changes can be made compatible with existing Epytext markup with some
smart logic (i.e. new syntax if effective if : is left out).

Now, tell my why this wouldn't be possible or I start to submit patches :)

-- 
Mikko Ohtamaa
Red Innovation Ltd.
+358 40 743 9707
www.redinnovation.com
Every problem is solvable if you can throw enough energy drinks at it

Re: [Epydoc-devel] Remove timestamps

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

Torsten Bronger write:
> Is it possible to get rid of the timestamps at the bottom of each
> generated page?  [...]

This was implemented, as a --suppress-timestamp command-line option
and boolean 'timestamp' option in the config file, in svn revision
1698.

-Edward

[Epydoc-devel] epydoc 3.0.1 released

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

It turned out that a last-minute patch that went in before the epydoc
3.0 release broke the GUI interface; so I just fixed the problem, and
put out a 3.0.1 release.

-Edward

[Epydoc-devel] epydoc 3.0 released

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

Announcing epydoc 3.0
~~~~~~~~~~~~~~~~~~~~~
  Webpage: http://epydoc.sourceforge.net/
  Download: http://tinyurl.com/yoo6d7

Epydoc is a tool for generating API documentation for Python modules,
based on their docstrings.  A lightweight markup language called
epytext can be used to format docstrings, and to add information about
specific fields, such as parameters and instance variables.  Epydoc
also understands docstrings written in reStructuredText, Javadoc, and
plaintext.  For some examples of the documentation generated by
epydoc, see:

  - The API documentation for epydoc.
    <http://epydoc.sourceforge.net/api/>

  - The API documentation for the Python 2.5 standard library.
    <http://epydoc.sourceforge.net/stdlib/>

  - The API documentation for NLTK, the natural language toolkit.
    <http://nltk.sourceforge.net/lite/doc/api/>

Improvements in Version 3.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 3.0 of epydoc adds support for extracting documentation
information using both introspection (i.e., importing & inspecting the
modules programmatically) and parsing (i.e., reading the source code of
the modules); and for combining both sources of information.  This is
important because each source has its own advantages and disadvantages
with respect to the other. See the epydoc FAQ for more information
about the relative benefits of introspection and parsing, and why it's
good to merge information from both sources:

    http://epydoc.sourceforge.net/faq.html#introspect_vs_parse

Version 3.0 also adds the following features:

  * Support for variable docstrings.

  * Automatic generating of source code graphs, including class trees,
    package trees, uml class graphs, and import graphs.

  * Syntax highlighted source code, including links from identifiers
    back into the documentation.

For more details about what's new in Epydoc 3.0, see:

    http://epydoc.sourceforge.net/whatsnew.html

----------------------------------------------------------------------
Edward Loper       ed...@gr...
                   http://www.cis.upenn.edu/~edloper/
----------------------------------------------------------------------

Re: [Epydoc-devel] module level variables (constants) missing

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

On Jan 21, 2008 7:26 PM, Silverstein <he...@sc...> wrote:
> Using Epydoc version 2.1 on Linux the html that is generated does not
> include the module-level variables.  For example, we want to include
> some constants for people to use.  So we have something like the
> following at the top of the module:
>
> # Constants for select actions
> ADD, REPLACE, INVERT, ALL, NONE = range(5)

First, I'd recommend using epydoc 3.0 -- even though it's in beta, I
consider it more stable & robust than epydoc 2.1.  And it's got some
very nice new features.

Using epydoc 3.0, these variables should get documented *if* epydoc
can import the module in question.  If not (i.e., if it has to fall
back on source code parsing), then it won't be able to figure out the
values, so it won't document these variables.  But if they were listed
one-per-line, then source code parsing would be able to figure it out.

-Edward

[Epydoc-devel] module level variables (constants) missing

[Silverstein <he...@sc...>]

Using Epydoc version 2.1 on Linux the html that is generated does not
include the module-level variables.  For example, we want to include
some constants for people to use.  So we have something like the
following at the top of the module:

# Constants for select actions
ADD, REPLACE, INVERT, ALL, NONE = range(5)


I do not see a way to get these to show up in the documentation.  Is
there some way to do this?

If not, should I file an enhancement request?

Herc

[Epydoc-devel] Remove timestamps

[Torsten B. <br...@ph...>]

Hall=F6chen!

Is it possible to get rid of the timestamps at the bottom of each
generated page?  My problem is that after each epydoc run, I use
rsynch to copy the pages on the webserver, and each time it has to
copy everything because just the timestamps changed (and little
else).  Thank you!

Tsch=F6,
Torsten.

--=20
Torsten Bronger, aquisgrana, europa vetus
                                      Jabber ID: br...@ja...
               (See http://ime.webhop.org for further contact info.)

Re: [Epydoc-devel] Package document problem?

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

Ted Drain ha scritto:
> Thanks.  That does help a little but my tree view and package doc 
> page are still showing the 'subpackage' foo even though it's not 
> listed in __all__.
> 
> I tried setting show private to no but that didn't change this behavior.

Yes, __all__ moves the class parenthood, but doesn't make the original module 
private. AFAICT you can only make the module private by prefixing its name 
with a '_' - i can't remember if there are other ways but i suspect no.

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

Re: [Epydoc-devel] Package document problem?

[Ted D. <ted...@jp...>]

Thanks.  That does help a little but my tree view and package doc 
page are still showing the 'subpackage' foo even though it's not 
listed in __all__.

I tried setting show private to no but that didn't change this behavior.

Ted

At 01:42 PM 12/4/2007, Daniele Varrazzo wrote:
>Ted Drain ha scritto:
>>I'm trying to create documentation for a package in a way that 
>>shows the programmatic layout of the objects.  For example:
>>pkg/__init__.py:
>>      from foo import bar
>>pkg/foo.py:
>>      class bar: ...
>>I'm using the v3 beta release.  Parsing is turned off, 
>>introspection is turned on.  I'd like the docs to show something like this:
>>pkg/bar
>>instead I get:
>>pkg/foo
>>      foo/bar
>>The problem is that foo is just a file - it's not a module and is 
>>not used by anyone who is trying to reference the package.  I'd 
>>like the docs to reflect how you need to write your code - i.e.:
>>import pkg
>>x = pkg.bar()
>>Am I missing something fundamental here?  I've tried every 
>>combination of introspect and parse but the docs always look the same.
>
>You can try adding __all__ = ['bar'] in pkg.__init__: it should 
>enforce to epydoc that pkg is bar's parent in the public interface, 
>and that foo.py is just an implementative detail.
>
>The feature should be independent from the analysis (parsing vs. 
>introspection) technique.
>
>Bye!
>
>--
>Daniele Varrazzo - Develer S.r.l.
>http://www.develer.com

Ted Drain     Jet Propulsion Laboratory   ted...@jp...    

Re: [Epydoc-devel] Package document problem?

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

Ted Drain ha scritto:
> I'm trying to create documentation for a package in a way that shows 
> the programmatic layout of the objects.  For example:
> 
> pkg/__init__.py:
>      from foo import bar
> 
> pkg/foo.py:
>      class bar: ...
> 
> I'm using the v3 beta release.  Parsing is turned off, introspection 
> is turned on.  I'd like the docs to show something like this:
> 
> pkg/bar
> 
> instead I get:
> 
> pkg/foo
>      foo/bar
> 
> The problem is that foo is just a file - it's not a module and is not 
> used by anyone who is trying to reference the package.  I'd like the 
> docs to reflect how you need to write your code - i.e.:
> 
> import pkg
> x = pkg.bar()
> 
> Am I missing something fundamental here?  I've tried every 
> combination of introspect and parse but the docs always look the same.

You can try adding __all__ = ['bar'] in pkg.__init__: it should enforce to 
epydoc that pkg is bar's parent in the public interface, and that foo.py is 
just an implementative detail.

The feature should be independent from the analysis (parsing vs. 
introspection) technique.

Bye!

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

[Epydoc-devel] Package document problem?

[Ted D. <ted...@jp...>]

I'm trying to create documentation for a package in a way that shows 
the programmatic layout of the objects.  For example:

pkg/__init__.py:
     from foo import bar

pkg/foo.py:
     class bar: ...

I'm using the v3 beta release.  Parsing is turned off, introspection 
is turned on.  I'd like the docs to show something like this:

pkg/bar

instead I get:

pkg/foo
     foo/bar

The problem is that foo is just a file - it's not a module and is not 
used by anyone who is trying to reference the package.  I'd like the 
docs to reflect how you need to write your code - i.e.:

import pkg
x = pkg.bar()

Am I missing something fundamental here?  I've tried every 
combination of introspect and parse but the docs always look the same.

Thanks,
Ted
Ted Drain     Jet Propulsion Laboratory   ted...@jp...    

Re: [Epydoc-devel] pdflatex support?

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

On Nov 15, 2007, at 8:49 AM, Neal Becker wrote:

> Would be nice to allow usage of pdflatex to convert to pdf, without  
> the 2step
> conversion of tex->ps->pdf.

In a post last April (http://sourceforge.net/mailarchive/forum.php? 
thread_name=1CA9ED19-0BF7-4E82-BB2C-BD0C132F0070% 
40nist.gov&forum_name=epydoc-devel), I offered up a number of patches  
to address our needs/desires for LaTeX and pdflatex was one of them.  
I have no idea where they stand relative to relative to trunk (my  
patches were against r1588 and the trunk is now at r1663).

[Epydoc-devel] sourcecode in pdf?

[Neal B. <ndb...@gm...>]

It seems that:

sourcecode: yes

works for html, but not pdf?  This is epydoc-3.0b1

[Epydoc-devel] pdflatex support?

[Neal B. <ndb...@gm...>]

Would be nice to allow usage of pdflatex to convert to pdf, without the 2step 
conversion of tex->ps->pdf.

Re: [Epydoc-devel] callgraph howto?

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

Neal Becker ha scritto:
> --- test.py ---
> def f():
>     return 1
> 
> def g():
>     return f()
> 
> g()
> ---------------
> 
> 
> python -m cProfile -o prof  test.py
> epydoc --pstat=prof --graph=all test.py
> 
> I don't see any call graph in the html output.  No errors either.  What am I 
> doing wrong? (epydoc-3.0b1)

mmm... it should have worked as you presumed, but it doesn't indeed.

I have checked that the profiling info read (in cli.py r1627 line 771) is 
blank (caller and callee are empty).

Testing with the profile states from the test suite of a package of mine, some 
callgraph is generated, but it doesn't seem complete.

I'll try to debug what happened in read_profiling_info().

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

[Epydoc-devel] callgraph howto?

[Neal B. <ndb...@gm...>]

--- test.py ---
def f():
    return 1

def g():
    return f()

g()
---------------


python -m cProfile -o prof  test.py
epydoc --pstat=prof --graph=all test.py

I don't see any call graph in the html output.  No errors either.  What am I 
doing wrong? (epydoc-3.0b1)

Re: [Epydoc-devel] Need to parse-only on just 1 file

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

Neal Becker ha scritto:
> I want to introspect a bunch of modules, but 1 needs to be parse-only.  Can 
> epydoc (3.0b1) do this?

Yes, it can: use --exclude-introspect="my\.module\.to\.parse" (dots are 
escaped becuse the argument is a regex pattern).

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

[Epydoc-devel] dot png option

[Neal B. <ndb...@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)

[Epydoc-devel] Need to parse-only on just 1 file

[Neal B. <ndb...@gm...>]

I want to introspect a bunch of modules, but 1 needs to be parse-only.  Can 
epydoc (3.0b1) do this?

[Epydoc-devel] Using RCS keyword with reStructuredText

[Saint G. <sai...@gm...>]

Hello,

I would like to use RCS keyword in comments with reStructuredText
markup language.
It seems that Docutils have some kind of RCS keyword processing, but
it doesn't seem to work in Epydoc.

For instance :

"""
:date: $Date$
:version: $Revision$
:author: $Author$
"""

Will get expanded (by CVS) :

"""
:date: $Date: 2007/09/19 13:52:04 $
:version: $Revision: 1.2 $
:author: $Author: saintger $

"""

But in the HTML report I still got the 'ugly' keyword :

Date: $Date: 2007/09/19 13:52:04 $
Version: $Revision: 1.2 $
Author: $Author: saintger $

Am I doing something wrong ?
Can someone send me a working example ?

Thanks in advance,

P.S. : I use the latest Epydoc package and the latest Docutils package
downloaded today...

Re: [Epydoc-devel] how to document methods imported from other modules?

[Paul P. <pog...@gm...>]

Edward Loper wrote:
> On Jun 27, 2007, at 8:40 PM, Paul Pogonyshev wrote:
> > However, there appears to be another problem...  If I document the
> > attached module, I get
> >
> > 	Method Details
> > 	object_context_manager(*args, **kwds)
> > 	
> > Instead of object_context_manager(self), which would be more logical.
> > Is that a known problem?
> 
> Unfortunately, the way contextmanager is defined, there's no good way  
> to introspect the arguments that are given to the wrapped function.   
> And without knowing what the decorator does, the source code parsing  
> can't just assume that the argument list stays the same.  The easiest  
> solution here is to add a line to the docstring, giving the correct  
> signature.  (The same thing needs to be done for builtin functions,  
> since their signature can't be introspected.)  So the following  
> should do what you want:
> 
>    @contextmanager
>    def object_context_manager(self):
>        """
>        object_context_manager(self)
> 
>        description...
>        """
>        ...
> 
> In the long term, it might be good to add contextmanager to the list  
> of decorators that epydoc's source code parser has explicit knowledge  
> about.  (Currently this list includes classmethod and staticmethod.)

Thank you, that works perfectly.  I think that adding contextmanager to
the list of known decorators is a good idea, but it is good that there
is a clean workaround for now.

Waiting for 3.0 final :)

Paul

Re: [Epydoc-devel] how to document methods imported from other modules?

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

On Jun 27, 2007, at 8:40 PM, Paul Pogonyshev wrote:
> However, there appears to be another problem...  If I document the
> attached module, I get
>
> 	Method Details
> 	object_context_manager(*args, **kwds)
> 	
> Instead of object_context_manager(self), which would be more logical.
> Is that a known problem?

Unfortunately, the way contextmanager is defined, there's no good way  
to introspect the arguments that are given to the wrapped function.   
And without knowing what the decorator does, the source code parsing  
can't just assume that the argument list stays the same.  The easiest  
solution here is to add a line to the docstring, giving the correct  
signature.  (The same thing needs to be done for builtin functions,  
since their signature can't be introspected.)  So the following  
should do what you want:

   @contextmanager
   def object_context_manager(self):
       """
       object_context_manager(self)

       description...
       """
       ...

In the long term, it might be good to add contextmanager to the list  
of decorators that epydoc's source code parser has explicit knowledge  
about.  (Currently this list includes classmethod and staticmethod.)

-Edward

Re: [Epydoc-devel] how to document methods imported from other modules?

[Paul P. <pog...@gm...>]

Edward Loper wrote:
> On Jun 24, 2007, at 2:43 PM, Paul Pogonyshev wrote:
> > Hi,
> >
> > My package supports Python 2.3 onwards.  However, I do provide some
> > methods that are only available on 2.5.  [...]
> > Question is: can I somehow pretend that my_cool_context_manager() is
> > defined with Main class, so it is documented in that class?
> 
> The problem here is that epydoc's source code parser sees the import  
> statement for my_cool_context_manager, so naturally it assumes that's  
> an imported object that should be documented elsewhere.  [...]

Actually, this seems to trick Epydoc into not seeing the importing:

        import _helper_2_5
        my_cool_context_manager = _helper_2_5.my_cool_context_manager

I get my_cool_context_manager documented in the target module, not in
the helper.  Now I simply disable documenting helper modules in my
script that invokes Epydoc and all looks correct.

However, there appears to be another problem...  If I document the
attached module, I get

	Method Details
	object_context_manager(*args, **kwds)
	 
Instead of object_context_manager(self), which would be more logical.
Is that a known problem?

Paul

Re: [Epydoc-devel] how to document methods imported from other modules?

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

On Jun 24, 2007, at 2:43 PM, Paul Pogonyshev wrote:
> Hi,
>
> My package supports Python 2.3 onwards.  However, I do provide some
> methods that are only available on 2.5.  [...]
> Question is: can I somehow pretend that my_cool_context_manager() is
> defined with Main class, so it is documented in that class?

The problem here is that epydoc's source code parser sees the import  
statement for my_cool_context_manager, so naturally it assumes that's  
an imported object that should be documented elsewhere.  There are a  
few possible work-arounds, none of which I'm entirely happy with.   
One is to use --introspect-only to disable source code parsing.   
Without the source code parsing, epydoc has no way to know that you  
imported the function (since you're explicitly modifying the  
function's __module__), so it will document it as part of your Main  
class.  The remaining work-arounds involve "hiding" the import from  
epydoc's source code parser.  For example, you could use the  
__import__ function instead of an import statement:

     my_cool_context_manager = \
         __import__('_helper_2_5').my_cool_context_manager

If it were a module-level function, rather than a class function,  
then you could get the desired behavior by explicitly defining  
__all__ and listing the imported object there -- epydoc treats an  
object as 'locally defined' (not imported) if it's listed explicitly  
in __all__, even if epydoc can tell that it's really imported.  This  
is useful for modules whose sole purpose is to collect together  
objects that are actually defined in other 'private' modules.   
Perhaps something could be done similar here -- epydoc could look for  
a class variable __all__, and treat anything listed there as if it  
weren't imported.  For consistency, epydoc would also treat member  
variables as private iff they are not listed in the class __all__  
variable.

Would that solution work for you?  If so, I'll add a feature request  
for this on the epydoc sourceforge page.  Unfortunately, I probably  
won't have time to implement it myself in the near future.  But of  
course, patches are always welcome!

-Edward

[Epydoc-devel] how to document methods imported from other modules?

[Paul P. <pog...@gm...>]

Hi,

My package supports Python 2.3 onwards.  However, I do provide some
methods that are only available on 2.5.  They are not essential, just
syntactic sugar, but they are nice.  (Context managers are only
available in 2.5.)

Rather than explaining how I do this, I attach two files that mimic
my approach.  That also shows why I need a separate module.

Question is: can I somehow pretend that my_cool_context_manager() is
defined with Main class, so it is documented in that class?

Paul