epydoc-devel — Discussions about epydoc development

[Epydoc-devel] Patch for handling newer Graphviz version information.

[Edward d'A. <ed...@nm...>]

Hi Ed,

I am the developer of a number of projects (http://www.nmr-relax.com/,
https://gna.org/projects/minfx/, https://gna.org/projects/bmrblib/,
https://gna.org/projects/nessy/) and use Epydoc for compiling a lot of
API documentation (http://www.nmr-relax.com/api/ and
http://home.gna.org/minfx/).  Due to epydoc appearing to be long ago
abandoned, I thought I'd look into it a bit more.  Some basic
maintenance to keep epydoc alive - for example Python 3 support -
would be rather trivial.  Especially for Linux distributions which
often package epydoc.

I tried playing with the svn repository code but the first thing I
noticed was that the 'dot' Graphviz graphic files were no longer
produced.  This broke at r1805:

-----
r1805 | edloper | 2008-02-27 21:24:06 +0100 (Wed, 27 Feb 2008) | 3 lines
Changed paths:
   M /trunk/epydoc/src/epydoc/docwriter/dotgraph.py

- If the dot executable is not found, issue an error, and don't try to
  generate further graphs.
-----

The problem is because the version information from Graphviz is now
formatted differently:

[edward@localhost src]$ dot -V
dot - graphviz version 2.34.0 (20140110.2222)
[edward@localhost src]$

So the get_dot_version() function in the epydoc.docwriter.dotgraph
module no longer works and returns a version of (0,).  Please find
attached a patch to fix this.  How do I go about getting this added to
the repository?  The patch simply adds a second hardcoded Graphviz
version string format which is set up as a fall-back if the first
pattern does not work.

Cheers,

Edward


P. S.  I was pleasantly surprised to see that there has been a lot of
development (up to 2009-02-03) since the 3.0.1 release (2008-01-30).
Is there anything that should be known about these changes?  Is there
a good reason why these changes were not released as version 3.0.2?

[Epydoc-devel] Generating callgraph for epydoc-3.0.1

[Shakthi K. <sha...@gm...>]

Hi,

I am trying to get the callgraph generated for epydoc-3.0.1 sources
using epydoc-3.0.1 on Fedora 15 using:

 $ python -m "profile" -o profile.out epydoc/*.py

 $ epydoc -v -o html/api --name epydoc --css white --url
http://epydoc.sourceforge.net --inheritance listed --graph callgraph
--pstat=profile.out epydoc

I get the following output:

=== OUTPUT ===

 [
Warning: Ignoring docstring comment block followed by a blank line in
        u'/usr/lib/python2.7/site-packages/epydoc/cli.py' on line
        1060
Warning: Ignoring docstring comment block followed by a blank line in
        u'/usr/lib/python2.7/site-packages/epydoc/cli.py' on line
        1061
Warning: Ignoring docstring comment block followed by a blank line in
        u'/usr/lib/python2.7/site-packages/epydoc/cli.py' on line
        1062
...
...
...
 [....................
Warning: No information available for
        epydoc.markup.restructuredtext.OptimizedReporter's base
        docutils.utils.Reporter
 [....................
Warning: No information available for
        epydoc.markup.restructuredtext._DocumentPseudoWriter's base
        docutils.writers.Writer
 [....................
Warning: No information available for
        epydoc.markup.restructuredtext._EpydocHTMLTranslator's base
        docutils.writers.html4css1.HTMLTranslator
 [....................
Warning: No information available for
        epydoc.markup.restructuredtext._EpydocLaTeXTranslator's base
        docutils.writers.latex2e.LaTeXTranslator
 [....................
Warning: No information available for
        epydoc.markup.restructuredtext._SplitFieldsTranslator's base
        docutils.nodes.NodeVisitor
 [....................
Warning: No information available for
        epydoc.markup.restructuredtext._SummaryExtractor's base
        docutils.nodes.NodeVisitor
 [....................
Warning: No information available for
        epydoc.markup.restructuredtext._TermsExtractor's base
        docutils.nodes.NodeVisitor
 [....................
Warning: No information available for
        epydoc.markup.restructuredtext.dotgraph's base
        docutils.nodes.image

...
...

=== END ===

I see the callgraph at http://epydoc.sourceforge.net/api/ in the
different modules, but, I am not able to generate it locally. What
could I be missing?

Appreciate any help in this regard.

Thanks!

SK

P.S.: Sorry for posting in this list. I couldn't find a epydoc-users list.

-- 
Shakthi Kannan
http://www.shakthimaan.com

Re: [Epydoc-devel] turn off documentation of __new__, __repr__, etc.

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

On Fri, Jun 25, 2010 at 4:06 PM, John Dennis <jd...@re...> wrote:
> I currently use epydoc for a CPython extension module (i.e. it's
> entirely written in C). Epydoc seems to always want to include
> documentation for things like __new__, __repr__, __str__, etc that
> really should be hidden from the user. The only thing the doc says is
> "Overrides: object.__repr__". It just clutters up the doc obscuring the
> important documentation.

Hi,

can't remember if there's a switch to disable "magic" methods as it's
a long time I'm not using Epydoc. But maybe using --inheritance=listed
could reduce the clutter, as the docstrings you see are the ones
defined on "object".

-- Daniele

[Epydoc-devel] turn off documentation of __new__, __repr__, etc.

[John D. <jd...@re...>]

I currently use epydoc for a CPython extension module (i.e. it's 
entirely written in C). Epydoc seems to always want to include 
documentation for things like __new__, __repr__, __str__, etc that 
really should be hidden from the user. The only thing the doc says is 
"Overrides: object.__repr__". It just clutters up the doc obscuring the 
important documentation.

How do I turn off or filter out that kind of "noisy" doc?

Also, for the __init__ method I always get this:

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

But the class is documented along with the __init__ parameters.

I do see a common thread, it seems like all the "noisy" useless doc are 
for things in CPython which do not have a way to associate a doc string 
(e.g. those things which are referenced by the PyTypeObject structure 
(i.e. tp_*).

Am I doing something wrong?

-- 
John Dennis <jd...@re...>

Looking to carve out IT costs?
www.redhat.com/carveoutcosts/

[Epydoc-devel] How to? epydoc --top=README

[Phlip <phl...@gm...>]

How do you populate the index.html output with your (insanely clever)
contents of your README file?

When I try the obvious notations, I get:

Warning: Identifier 'README' looks suspicious; using it anyway.
Warning: Could not find top page 'README'; using module-tree.html instead

And, yes, the README is included in the input list, and yes I get a
script-README-module.html

-- 
  Phlip
  http://c2.com/cgi/wiki?ZeekLand

Re: [Epydoc-devel] Proposal: give possibility to use derived customized HTMLWriter

[Thomas K. <sou...@sc...>]

Hi,

I forgot a detail for my patch. To use this patch, and especially the
extension for checker class, it's necessary also to extend basic
DocChecker class. There must be too a extra argument like in HTMLWriter
class to receive commandline options, if necessary.

Here is this patch:

diff -ruN epydoc-3.0.1_orig/epydoc/checker.py epydoc_3.0.1/epydoc/checker.py
--- epydoc-3.0.1_orig/epydoc/checker.py	2007-08-02 18:58:09.000000000 +0200
+++ epydoc_3.0.1/epydoc/checker.py	2008-06-04 18:54:29.000000000 +0200
@@ -144,7 +144,7 @@

     ALL = ALL_T + ALL_C + PRIVATE

-    def __init__(self, docindex):
+    def __init__(self, docindex, **extra_args):
         """
         Create a new C{DocChecker} that can be used to run checks on
         the documentation of the objects documented by C{docindex}
@@ -152,6 +152,8 @@
         @param docindex: A documentation map containing the
             documentation for the objects to be checked.
         @type docindex: L{Docindex<apidoc.DocIndex>}
+        @param extra_args: extra arguments and options, actually not used
+        @type extra_args: C{dict}
         """
         self._docindex = docindex

[Epydoc-devel] Proposal: give possibility to use derived customized HTMLWriter

[Thomas K. <sou...@sc...>]

Hi,

below is a patch, to extend cli.py with the possibility, to use an
customized HTMLWriter (or even for development too) without changing
epydoc itself. I use such Customization for myself to have some changes
in created html file as, for example, use class attributes for defining
view style by css file instead of hardcoding view style in code.

Goal is, to have a commandline option to specify this customized class.
By default the HTMLWriter class is used, so it's behavior is the same as
before, if somebody do not use this option.

In this patch I have also used same mechanism for checker class. But it
can be used in the same way for other output targets.

Here is the patch:

diff -ruN epydoc-3.0.1_orig/epydoc/cli.py epydoc_3.0.1/epydoc/cli.py
--- epydoc-3.0.1_orig/epydoc/cli.py	2008-01-29 14:21:23.000000000 +0100
+++ epydoc_3.0.1/epydoc/cli.py	2008-06-04 18:55:11.000000000 +0200
@@ -180,6 +180,10 @@
         action="store_const", dest="action", const="html",
         help="Write HTML output.")

+    action_group.add_option("--html-writer-class",
+        action="store", dest="action_html_writer_class", default = None,
+        help="HTML writer class as 'import.path.to.class:class'")
+
     action_group.add_option("--text",
         action="store_const", dest="action", const="text",
         help="Write plaintext output. (not implemented yet)")
@@ -204,6 +208,10 @@
         action="store_const", dest="action", const="check",
         help="Check completeness of docs.")

+    action_group.add_option("--check-checker-class",
+        action="store", dest="action_check_checker_class", default = None,
+        help="checker class for check docu as
'import.path.to.class:class'")
+
     action_group.add_option("--pickle",
         action="store_const", dest="action", const="pickle",
         help="Write the documentation to a pickle file.")
@@ -815,7 +823,21 @@

 def write_html(docindex, options):
     from epydoc.docwriter.html import HTMLWriter
-    html_writer = HTMLWriter(docindex, **options.__dict__)
+    istr = options.action_html_writer_class
+    wr = None
+    if istr:
+        try:
+            ipath, imod = istr.split(":", 1)
+            mod = __import__(ipath, globals(), locals(), [imod], -1)
+            wr = getattr(mod, imod)
+            if not issubclass(wr, HTMLWriter):
+                wr = None
+                raise Exception, "class isn't subclass of HTMLWriter"
+        except Exception, e:
+            from log import error
+            error("html writer setting '%s': %s" % (istr, str(e)))
+    if wr is None: wr = HTMLWriter
+    html_writer = wr(docindex, **options.__dict__)
     if options.verbose > 0:
         log.start_progress('Writing HTML docs to %r' % options.target)
     else:
@@ -951,7 +973,22 @@

 def check_docs(docindex, options):
     from epydoc.checker import DocChecker
-    DocChecker(docindex).check()
+
+    istr = options.action_check_checker_class
+    ckr = None
+    if istr:
+        try:
+            ipath, imod = istr.split(":", 1)
+            mod = __import__(ipath, globals(), locals(), [imod], -1)
+            ckr = getattr(mod, imod)
+            if not issubclass(ckr, DocChecker):
+                ckr = None
+                raise Exception, "class isn't subclass of DocChecker"
+        except Exception, e:
+            from log import error
+            error("doc checker setting '%s': %s" % (istr, str(e)))
+    if ckr is None: ckr = DocChecker
+    ckr(docindex, **options.__dict__).check()

 def cli():
     # Parse command-line arguments.

[Epydoc-devel] Bugs for epydoc 3.0.1 and current svn

[Thomas K. <sou...@sc...>]

Hi,

@list admin: please ignore mail with same topic from yesterday, sender
mail address was wrong!

As announced a few days before: 2 Bugs, which I have found.

This is a uninitialized variable. Because center is True on default
HTMLWriter class, this bug isn't seen normaly.

diff -ruN epydoc-3.0.1_orig/epydoc/docwriter/dotgraph.py
epydoc_3.0.1/epydoc/docwriter/dotgraph.py
--- epydoc-3.0.1_orig/epydoc/docwriter/dotgraph.py	2008-01-28
19:15:33.000000000 +0100
+++ epydoc_3.0.1/epydoc/docwriter/dotgraph.py	2008-06-04
18:41:02.000000000 +0200
@@ -168,6 +168,7 @@
             title_align = 'center'
             table_width = ''

+        s = ''
         if center: s = '<center>'
         if title or caption:
             s += ('<table border="0" cellpadding="0" cellspacing="0" '

The second happens, if docutils > 0.5 will be used. data attribute on
Node class isn't available after version 0.5. But on other places in
code method astext is used, so this fix should also work with docutils
version 0.5.

diff -ruN epydoc-orig/epydoc/markup/restructuredtext.py
epydoc-new/epydoc/markup/restructuredtext.py
--- epydoc-orig/epydoc/markup/restructuredtext.py	Mon Jan 28 18:15:34 2008
+++ epydoc-new/epydoc/markup/restructuredtext.py	Thu May  7 07:18:33 2009
@@ -304,10 +304,11 @@
         # Extract the first sentence.
         for child in node:
             if isinstance(child, docutils.nodes.Text):
-                m = self._SUMMARY_RE.match(child.data)
+                data = child.astext()
+                m = self._SUMMARY_RE.match(data)
                 if m:
                     summary_pieces.append(docutils.nodes.Text(m.group(1)))
-                    other = child.data[m.end():]
+                    other = data[m.end():]
                     if other and not other.isspace():
                         self.other_docs = True
                     break
@@ -489,10 +490,11 @@
             if (len(fbody[0]) > 0 and
                 isinstance(fbody[0][0], docutils.nodes.Text)):
                 child = fbody[0][0]
-                if child.data[:1] in ':-':
-                    child.data = child.data[1:].lstrip()
-                elif child.data[:2] in (' -', ' :'):
-                    child.data = child.data[2:].lstrip()
+                data = child.astext()
+                if data[:1] in ':-':
+                    data = data[1:].lstrip()
+                elif data[:2] in (' -', ' :'):
+                    data = data[2:].lstrip()

             # Wrap the field body, and add a new field
             self._add_field(tagname, arg, fbody)

Others (some proposals from me) will come with extra posting.

cu, Thomas

[Epydoc-devel] Some bugs, how to send

[Thomas K. <sou...@sc...>]

Hi,

I have 2 Bugs on epydoc 3.0.1 (but also still in current svn) and the
question: where to send this? Still as patches here or what else.

One of this bugs is connected with docutils, with versions after 0.5 the
node object hasn't data attribute, but astext method. (which is also
used now in epydoc, but inconsistent)

Second is an uninitialised variable.

Then I have also some proposals for improvements: (and, for the first,
also an patch, the second proposal is in work) the first is, to use an
custom class instead of HTMLWriter class to have some style changes for
example without building a special epydoc version for me. ;-) The same
for DocChecker class (the same mechanism). The second is connected with
default encoding: current it's fix coded to ISO8859-1 on some places
with different writing styles. I propose a command line option with a
default to ISO8859-1 (I prefer UTF-8) and then replace all occurences
for encoding with that setting (as a global value in a modul, it would
be the less invasive solution on my opinion)

If I know, where, then I can send in this patches.

cu, Thomas

Re: [Epydoc-devel] Setting DocChecker.PARAM for functions requires documentation of 'self'

[<li...@ev...>]

Solution:

class MyDocChecker(DocChecker, object):
    """
    Subclass of epydoc's doc checker;
    override function methods here.
    """
    def _check_func(self, doc):
        """
        Overrides the default epydoc checker's function checker.  
        
        Removes 'self' and 'cls' as arguments that need documentation.
        
        @param doc: epydoc document object
        @return: Whatever DocChecker._check_func() returns.
        """
        try:
            doc.posargs.remove(u'self')
        except:
            pass
        
        try:
            doc.posargs.remove(u'cls')
        except:
            pass
        
        return super(MyDocChecker, self)._check_func(doc)

[Epydoc-devel] Setting DocChecker.PARAM for functions requires documentation of 'self'

[<li...@ev...>]

Hello,

I'm using epydoc to check and enforce documentation completeness for a
project.  It seems that when I check the documentation of functions with
the following combination of checks --

DocChecker.FUNC | DocChecker.DESCR | DocChecker.RETURN |
DocChecker.PARAM

-- epydoc will complain that "Argument(s) not described" if the
parameter 'self' is not documented.  Since 'self' means the same thing
in pretty much every function in existence, this contributes nothing but
noise to the docstrings.  I'm wondering if there is an easy way to shut
this off.

For reference, I am not using 'epydoc --check' directly, but rather
importing what I need, building a DocIndex, attaching it to a
DocChecker, and running the checks on it from Python.

Thanks!

Re: [Epydoc-devel] Epydoc crashes

[Damien B. - U. <dam...@ub...>]

Le Tue, 23 Sep 2008 10:58:24 -0400,
"Edward Loper" <ed...@br...> a écrit :
> (i.e., you're assigning a string value to __all__, not a list or tuple
> -- remember, it's the comma(s) that makes a tuple, not the
> parentheses.)  Apparently Python is happy with this and does the right
> thing, but epydoc doesn't.  If you just want epydoc to work on your
> file, then change that line to:
> 
> __all__ = ("global_skin",)


Ho ! You're right !

As well as being a sexy doc generator, Epydoc is also a very powerful
syntax checker ! It detects errors that pychecker, pyflakes and pylint
missed !

Thank you for your quick answer.

Damien.

Re: [Epydoc-devel] Epydoc crashes

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

On Tue, Sep 23, 2008 at 10:09 AM, Damien Boucard - UbiCast
<dam...@ub...> wrote:
> An unhandled python exception crashes Epydoc command (during source
> parsing, I guess).

Yep, anytime epydoc crashes, that's a bug in epydoc. :)  In this case,
epydoc is making assumptions about what the value of __all__ will look
like that may not always be true..  In particular, it's assuming that
it will contain a list or tuple of strings.  In contrast, your module
says:

__all__ = ("global_skin")

which is actually equivalent to:

__all__ = "global_skin"

(i.e., you're assigning a string value to __all__, not a list or tuple
-- remember, it's the comma(s) that makes a tuple, not the
parentheses.)  Apparently Python is happy with this and does the right
thing, but epydoc doesn't.  If you just want epydoc to work on your
file, then change that line to:

__all__ = ("global_skin",)

(Note the comma.)  But this is also something that should get fixed in
epydoc, so I'll add a bug report for it to the epydoc bug tracker on
sourceforge.

-Edward

[Epydoc-devel] Epydoc crashes

[Damien B. - U. <dam...@ub...>]

Hi,

An unhandled python exception crashes Epydoc command (during source
parsing, I guess).

I used the python-epydoc package from Ubuntu Gutsy (v.3.0beta1). I
also tried with Epydoc v3.0.1 (installed from Ubuntu Intrepid source
package) with the same result.

My Python interpreter is v2.5.1.

The first attached file contains the command line I used and the output
trace I get.

The second attached file contains the python module on which Epydoc
crashes (skin.py). Note that it is the only file, from my Python
package, where Epydoc crashes.

I don't know if my docstring syntax is correct, but I guess
that even if it was not, Epydoc should not crash but should give me a
human-readable error message.

Thank you in advance for your help.

Damien Boucard.

Re: [Epydoc-devel] Convention for referencing params in function documentation

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

On Thu, Apr 17, 2008 at 1:31 PM, Joseph Turian <tu...@gm...> wrote:
> What is the appropriate convention for referencing params in function
> documentation?
> e.g.
>
> def max(x):
>    """
>    @return: The largest element of I{x}.
>    """

In epytext, I usually just use C{x} for function parameters.  In
restructured text, I usually use `x`.  Both conventions have the
disadvantage you mention -- that it would be nontrivial to change
formatting later on.  But I've never found myself wanting to change
the formatting, and don't expect to in the future.  I don't think the
potential of maybe wanting to change formatting in the future is worth
the overhead of adding new markup syntax (in terms of human memory
space and markup learning curve).

(For some projects, I would just write x -- i.e., no markup. :)

-Edward

[Epydoc-devel] Convention for referencing params in function documentation

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

What is the appropriate convention for referencing params in function
documentation?
e.g.

def max(x):
   """
   @return: The largest element of I{x}.
   """

(Obviously, I could make @param x:, but this is just for the sake of
explanation.)

Is there a convention for annotation params in the function documentation?
I could italicize them all, but this is brittle and one may want to change
the formatting later on.

Thanks,
   Joseph

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

[Epydoc-devel] regexes in config files

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

Hallöchen!

I'd like to use the option "exclude-parse" in the configuration
file.  However, how can I prevent the __init__.py file (and only
this) from being parsed?  I tried "path.to.package$" but this
doesn't work.

Tschö,
Torsten.

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

[Epydoc-devel] Problem with cross-referencing

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

Hallöchen!

Here is an excerpt of one of my docstrings:

        """This method generates the actual output, i.e. writes to files,
        creates subdirectories, calls post-processing conversion programs,
        prepares all images etc.  It is called from the
        `parser.sectioning.Document.generate_output` method in the
        `sectioning.Document` root node. ...."""

The given cross references are minimal.  My question is, why do I
have to give the package name ("parser" in this case) for pointing
to the method, whereas this is not necessary for pointing to the
class?  I had to switch off source code parsing for the module
sectioning.py.

Tschö,
Torsten.

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

Re: [Epydoc-devel] Problem (and how to fix it) about png images in pdf

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

On Mon, Mar 31, 2008 at 9:42 AM, Manuel <man...@ti...> wrote:
>  I'm using images with restructuredtext sintax (ubuntu 7.10). [...]
>
>  LaTeX Error: Cannot determine size of graphic...
>
>  The problem is quickly fixed using pdfLatex instead latex.
>  Maybe useful to have this option available in epydoc configuration file.

Thanks for this report.  Note that the version of epydoc in svn now
defaults to using pdflatex instead of latex if you specify --pdf
(unless you also specify --ps or --dvi).

-Edward

Re: [Epydoc-devel] Wrapping ling lines in source snippets

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

>  I use doctests and so I have long lines in my docstrings sometimes,
>  [...]
>  Unfortunately, this spoils the HTML frame because it forces a
>  horizontal scrollbar.  Is it possible to break this somehow?

If you don't plan to use doctest to test the code, then you could just
wrap the line in your source file.  I.e.:

>     >>> setting.set_value(1)
>     Traceback (most recent call last):
>       ...
>     SettingWrongTypeError: setting 'key = 1': new value
>     of type 'int' is unequal to previous type 'unicode'

If you do plan to use doctest to test the code, then you could still
wrap the line, but you'd need to use a directive -- either
doctest:+NORMALIZE_WHITESPACE or doctest:+IGNORE_EXCEPTION_DETAIL; see
the documentation for doctest [1] for details.  E.g.:

>     >>> setting.set_value(1)  # doctest: +NORMALIZE_WHITESPACE
>     Traceback (most recent call last):
>       ...
>     SettingWrongTypeError: setting 'key = 1': new value
>     of type 'int' is unequal to previous type 'unicode'

-Edward

[1] http://docs.python.org/lib/module-doctest.html

[Epydoc-devel] Wrapping ling lines in source snippets

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

Hallöchen!

I use doctests and so I have long lines in my docstrings sometimes,
e.g.

    >>> setting = Setting("key", "value")
    >>> setting.set_value("Hallo")
    >>> setting.value
    u'Hallo'
    >>> setting.set_value(1)
    Traceback (most recent call last):
      ...
    SettingWrongTypeError: setting 'key = 1': new value of type 'int' is unequal to previous type 'unicode'

Unfortunately, this spoils the HTML frame because it forces a
horizontal scrollbar.  Is it possible to break this somehow?

Tschö,
Torsten.

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

[Epydoc-devel] Problem (and how to fix it) about png images in pdf

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

Hi.
I'm using images with restructuredtext sintax (ubuntu 7.10).
They work fine, but when I compile to have the pdf version, I've notice of
this "classic" problem : 

LaTeX Error: Cannot determine size of graphic...

The problem is quickly fixed using pdfLatex instead latex.
Maybe useful to have this option available in epydoc configuration file.

Regards,

Manuel Bastioni

Re: [Epydoc-devel] --exclude pattern problem

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

Edward Loper ha scritto:
> On Sat, Mar 29, 2008 at 3:00 PM, oti...@ya...
> <oti...@ya...> wrote:
>>  In one of the modules I'm trying to generate the API for, a pretty big
>>  external module is imported (numpy). [...]
> 
> The problem that trips up epydoc is the combination of these two lines:
> 
>>   import numpy as N
>>   __all__ = ['bar','N']
> 
>>From the __all__ line, epydoc assumes that "foo.N" is part of foo, and
> so it decides it needs to document the value of N.  Of course, the
> value of N is the numpy module, so this goes off and documents numpy.
> 
> I just committed a patch to svn (revision 1810), which modifies the
> docintrospector to treat all module-valued variables as imported, even
> if they appear in __all__.  This will fix the problem of having numpy
> get documented when it shouldn't.  

If I have correctly understood the patch behavior, it prevents to "reshape" a 
package by defining the modules where it is more useful and make it accessible 
where it makes more sense. E.g. in a library:

   my_package/
     __init__.py
     _implementation_details/
       _my_module_unix.py
       _my_module_win32.py

where __init__.py contains:

   all = ['my_module']
   if sys.platform == 'win32':
     import _implementation_details._my_module_win32 as my_module
   else:
     import _implementation_details._my_module_unix as my_module

I think Epydoc should document that you can publicly access 
"my_package.my_module".

In this case I'd prefer the previous behavior: I believe the need to import 
the numpy as N doing "from somewherelse import *" is really something that can 
be done in a different way.

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

Re: [Epydoc-devel] --exclude pattern problem

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

On Sat, Mar 29, 2008 at 3:00 PM, oti...@ya...
<oti...@ya...> wrote:
>  In one of the modules I'm trying to generate the API for, a pretty big
>  external module is imported (numpy). [...]

The problem that trips up epydoc is the combination of these two lines:

>   import numpy as N
>   __all__ = ['bar','N']

>From the __all__ line, epydoc assumes that "foo.N" is part of foo, and
so it decides it needs to document the value of N.  Of course, the
value of N is the numpy module, so this goes off and documents numpy.

I just committed a patch to svn (revision 1810), which modifies the
docintrospector to treat all module-valued variables as imported, even
if they appear in __all__.  This will fix the problem of having numpy
get documented when it shouldn't.  But the generated documentation
won't include any docs for the "N" variable.  (It's not clear to me
what the documentation for that variable should be if it were
included, though, so hopefully that's not a problem.)

If you get a chance to check out the svn revision, please let me know
whether this solves your problem.  For instructions for using svn, see
the eypdoc webpage (http://epydoc.sf.net/).

Thanks,
-Edward

[Epydoc-devel] --exclude pattern problem

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

Dear epydoc devels, since I got a solution for my problem in less than 24
hours, I just thought I may try my luck again :-))
In one of the modules I'm trying to generate the API for, a pretty big 
external module is imported (numpy). I don't want to ship the numpy API
together with my module's API, but excluding "numpy" with the --exclude
switch doesn't help. An example:

foo/
foo/__init__.py

where __init__.py is:
  import numpy as N 
  bar = 1
  __all__ = ['bar','N']

ideally, when I generate the APi with:
epydoc --html --introspect-only --exclude numpy foo/__init__.py
I would like to see only my 'foo' module and my 'bar' variable documented, 
and not the whole numpy tree, which is what happens regardless of the
exclude option. 
What am I doing wrong?

thank you!

tiziano











      ____________________________________________________________________________________
Special deal for Yahoo! users & friends - No Cost. Get a month of Blockbuster Total Access now 
http://tc.deals.yahoo.com/tc/blockbuster/text3.com