epydoc-devel — Discussions about epydoc development

[Epydoc-devel] Epydoc + Doc-Utils = Better?

[Vicki B. <vl...@ir...>]

Has there been any thought regarding the possibility of Epydoc 
joining forces with the Doc-Utils project?
-- 
- V.
Vicki Brown <vl...@ir...> * Jabber: vl...@ir...
   Software Development Internal Technical Documentation
   http://www.cfcl.com/vlb/Jobweb/

Re: [Epydoc-devel] full project directory tree traversal

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

Vicki Brown wrote:
> The company where I work has a large CVS tree full of python sources. 
> Much of this code is in subdirectories (and many of those have 
> subdirectories of their own) but essentially none of it is in "official" 
> Python packages.
> 
> Is there a convenient way to run epydoc on a complete directory 
> hierarchy that isn't composed of Python Packages?

The decision to not traverse directories unless they're packages was
made intentionally -- sometimes this is what you want to do, and if
directories were always traversed, then there would be no way *not* to
include unwanted subdirectories.

Another option would be to add a flag that controls this behavior.  I'm
trying to keep the number of flags down, but if this is an important
feature for you, I might add one.

If you're in a unix-like environment, you might also consider using
find.  I.e., something like:

   epydoc `find mydir/ -name '*.py'`

which will find all .py files in mydir, and give them to epydoc.
Depending on what shell you use, this might also work:

   epydoc **/*.py

(Where "**" expands to "anything, including subdirectories.")  Other
build environments may have their own ways of doing the same thing.

> HappyDoc and Doxygen will traverse trees whether they are packages or not.
> But Doxygen converts Python source to "C++" 

I didn't realize that doxygen even works for python.

> What can we do?

You can do any one of the following:
   - use find, or an equivalant mechanism
   - ask me to add a flag to explicitly say to traverse subdirectories
     that aren't packages
   - make a convincing argument that traversing subdirectories that
     aren't packages is always the right thing to do, and so should be
     done by default.

-Edward

[Epydoc-devel] full project directory tree traversal

[Vicki B. <vl...@ir...>]

The company where I work has a large CVS tree full of python sources. 
Much of this code is in subdirectories (and many of those have 
subdirectories of their own) but essentially none of it is in 
"official" Python packages.

Is there a convenient way to run epydoc on a complete directory 
hierarchy that isn't composed of Python Packages?

HappyDoc and Doxygen will traverse trees whether they are packages or not.
But Doxygen converts Python source to "C++" and HappyDoc isn't the 
popular package. Epydoc is the popular package.

What can we do?
-- 
- V.
Vicki Brown <vl...@ir...> * Jabber: vl...@ir...
   Software Development Internal Technical Documentation
   http://www.cfcl.com/vlb/Jobweb/

[Epydoc-devel] Problem with latest docutils

[Eric H. <e-...@ne...>]

We've noticed a problem when using epydoc with the latest version of
docutils.  The HTML output is including <p> tags around the content making
it look, well, wrong.

I have some output examples that show this here:
http://www.ehuss.org/epydoc/

The change seems to be centered around CVS version 1.132 (or maybe 1.139?)
of docutils/writers/html4css1.py which altered the behavior of determining
if something should be a "compact paragraph".  This change was made in
November.  Thus docutils 0.3.5 works, but 0.3.7 does not.

We think that epydoc should not pass things to docutils that are documents
(because of the should_be_compact_paragraph method in html4css1 is
checking for that), but we are entirely unsure of what should be done to
fix this (if, perhaps, it is a problem with docutils).  Has anyone else
seen this, or know anything more about it?

-Eric

Re: [Epydoc-devel] Valid XHTML patch

[Fred L. D. Jr. <fd...@ac...>]

On Sunday 03 October 2004 03:51 pm, Jacek Konieczny wrote:
 > Today I looked into the Epydoc code and fixed the HTML generation.
 > I have attached the patch to the bug report.

This is wonderful news!

 > Some more things that could be done:
 > - Include alternate stylesheets in the output, so they can be chosen
 >   while browsing the documentation. That seems easy and I will probably
 >   do that soon.

Nice.

 > - XHTML Strict generation. That would probably need much more code
 >   changes and removal of frames support (or making it and option).

Hmm.  This sort of thing is just about one of the only places I find frames a 
proper approach.  Yes, it could be done without, but I'm not sure what the 
benefit is in practice.

It's too bad the XFrames specification was never made feasible.

 > I hope you will find my patch usefull and it will be applied to the
 > Epydoc code.

This certainly sounds like a good step.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>

[Epydoc-devel] Valid XHTML patch

[Jacek K. <ja...@bn...>]

Hello,

I am using Epydoc as the documentation generator for my project. It is
great in extracting the documentation, and the output looks nice (when
frames are disabled), but... I have checked the HTML output with
validating parser. And it was invalid.

I have looked into the HTML code, and although it was marked as XHTML
1.0 Transitional it was far from being any HTML (according to W3C
specifications). The code was invalid and ugly. Good example how not to
write HTML. I would be ashamed to publish such documents on my project's
page (I guess I am not the only one). So I have filled the bug report
#1039049 on the sourceforge.

Today I looked into the Epydoc code and fixed the HTML generation.
I have attached the patch to the bug report.

What the patch does:
- makes the HTML generated valid XHTML 1.0 Transitional and XHTML 1.0 Frameset,
- replaces deprecated elements (like <font/> and <center/>) with
  structural elements and/or proper style,
- replaces <b/> and <i/> (which are not recommended by W3C) with
  <strong/> and <em/> or other elements with semantics matching the
  usage (eg. <h1>). Wherever I could guess what the markup is I added
  a "class" attribute so the style of the element may be further
  changed.
- separates layout definition from predefined styles (which differ only 
  in colors) to a single string, so the same definitions are not
  repeated in css.py and may be modified in one place.
- escapes control characters in colorized regular expressions. Without
  that regexp like r'[\x00-1f]' would result with 0 byte included in the
  HTML output which is invalid and makes the rendering of the page
  inpredictable (some browser will treat the byte as EOF)

I tried to make the generated not differ from the ones generated without
the patch. And they should not differ much in any modern
standard-compliant browser. If they do -- it is a bug (unless the look
better now, of course). If they look worse in some
non-standard-compliant, but "important" browser (read: IE), than some
hack may be needed. But there is no reason to use invalid HTML (means to
do that with valid HTML may be found in the Net).

Some more things that could be done:
- Include alternate stylesheets in the output, so they can be chosen
  while browsing the documentation. That seems easy and I will probably 
  do that soon.
- XHTML Strict generation. That would probably need much more code
  changes and removal of frames support (or making it and option).
- drop using tables for layout. Epydoc doesn't do that much, as most of
  its output are real tables.
- Unicode support. The output could be alway UTF-8. But, I guess, a lot
  of Epydoc code would have to be updated, not only the HTML generation.
  Fortunately most code documentation is English only, even in
  international projects.

I hope you will find my patch usefull and it will be applied to the
Epydoc code.

Greets,
        Jacek

[Epydoc-devel] Feedback

[Thomas G. <gu...@th...>]

Hi,

Thank you for this wonderful tool!

Here comes some feedback:

- Typo: Error: '...' is not a *pacakge*

- Link to 'http://epydoc.sf.net' should use target="_top".
  Otherwise the page gets opened in the frame.
 (In the generated HTML, right frame)

- How can you add a docstring to a classvariable?

- 5.3. Epytext Errors:
   "Improper paragraph indentation" --> Please
   mention the  "literal block" syntax.

- index.html: Would be nice to have a link to the
 first characters:
 a, b, c, d, e, ...
 (Like in the index of the python standard library)

- I inherit from third party classes. Is it possible
  to exclude the docstrings of some methods?

- future.html: Latex output is on the todo list,
  but it is already implemented.

- "--check" should list broken crossreferences
  like "--html"

Unfortunately there is no standard way of
formating docstrings (restructeredtext vs.
epytext). It would be very nice if the python
community could agree on *one* version.

Please CC to me, I am not on the list.

Regards,
 Thomas  


-- 
Thomas Guettler <gu...@th...>
http://www.thomas-guettler.de

[Epydoc-devel] Suprressing documentation of third-party modules

[Ian H. <iha...@gn...>]

is there any way to stop epydoc from regenerating documentation for a separate module (wxPython in this case)
which is imported by our code?

Ian Haywood

-- 
PGP public key E750652E at wwwkeys.pgp.net
9BF0 67B7 F84F F7EE 0C42  C063 28FC BC52 E750 652E

Re: [Epydoc-devel] restructuredtext

[Robin D. <ro...@al...>]

Fred L. Drake, Jr. wrote:
> On Tuesday 27 April 2004 09:48 pm, Robin Dunn wrote:
>  > Yep, I've started using it this afternoon too.  Now if only it didn't
>  > take epydoc twice as long to generate wxPython docs using reST than it
>  > does with epytext...
> 
> I've done very little with epytext, so can't really compare the two 
> performance-wise.  Docutils definately takes a fairly heavy approach to 
> processing; I know Ed's done some work that should improve that somewhat, but 
> don't know if that's in the Docutils CVS yet.  The use of DOM nodes in 
> Docutils certainly causes it to squarely avoid the lightweight category.

Yep, I fully expected that using reST would have an impact, but was a 
little surprised that it was this much.  It's not really noticable when 
generating smaller file sets, but wxPython is big enough (almost 1000 
html files generated, some quite large) that the time difference is 
probably measured in minutes.  I havn't really measured it though, just 
gut feel at this point.

It's not a big deal though.  It's something that I can live with as once 
I get the basics worked out and figure out how I want to do various 
kinds of things I don't think I'll be rebuilding the docs more than a 
couple times a week, and will probably automate that.

-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!

Re: [Epydoc-devel] restructuredtext

[Fred L. D. Jr. <fd...@ac...>]

On Tuesday 27 April 2004 09:48 pm, Robin Dunn wrote:
 > Yep, I've started using it this afternoon too.  Now if only it didn't
 > take epydoc twice as long to generate wxPython docs using reST than it
 > does with epytext...

I've done very little with epytext, so can't really compare the two 
performance-wise.  Docutils definately takes a fairly heavy approach to 
processing; I know Ed's done some work that should improve that somewhat, but 
don't know if that's in the Docutils CVS yet.  The use of DOM nodes in 
Docutils certainly causes it to squarely avoid the lightweight category.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

Re: [Epydoc-devel] restructuredtext

[Robin D. <ro...@al...>]

Fred L. Drake, Jr. wrote:
> On Tuesday 27 April 2004 11:29 am, Robin Dunn wrote:
>  > What is the restructuredtext equivallent to L{object} ?
> 
> In Epydoc, the default reStructuredText "interpreted text role" is 
> "identifier", so you can simply use
> 
>     `object`
> 
> Epydoc seems to do quite well with turning that into a link to the 
> documentation for object.
> 

Yep, I've started using it this afternoon too.  Now if only it didn't 
take epydoc twice as long to generate wxPython docs using reST than it 
does with epytext...

-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!

Re: [Epydoc-devel] restructuredtext

[Fred L. D. Jr. <fd...@ac...>]

On Tuesday 27 April 2004 11:29 am, Robin Dunn wrote:
 > What is the restructuredtext equivallent to L{object} ?

In Epydoc, the default reStructuredText "interpreted text role" is 
"identifier", so you can simply use

    `object`

Epydoc seems to do quite well with turning that into a link to the 
documentation for object.

Or at least that's how I've been doing it.  ;-)


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

Re: [Epydoc-devel] restructuredtext

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

Robin Dunn wrote:

> What is the restructuredtext equivallent to L{object} ?

It's `object` (i.e., backticks).

-Edward

[Epydoc-devel] restructuredtext

[Robin D. <ro...@al...>]

What is the restructuredtext equivallent to L{object} ?

-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!

Re: [Epydoc-devel] Re: epydoc questions

[Robin D. <ro...@al...>]

Robin Dunn wrote:
> Edward Loper wrote:
> 
>> Robin Dunn wrote:
>>
>>>> But I'm sure you don't want *all* imported objects to be listed as 
>>>> if they're defined locally.
>>>
>>>
>>>
>>> Actually, in this case I do want all of them. 
>>
>>
>>
>> For this one module, maybe, but not in general, right?  So maybe what 
>> you want is a module-level way of saying "treat imported objects as 
>> locally defined" instead of an object-level one?
>>
>>> For the docs my preference would be that "core" and "wx.core" does 
>>> not show up anywhere, and that everything that lives in wx.core would 
>>> just be documented as "wx.Whatever".
>>
>>
>>
>> If "core" isn't listed in wx.__all__, then it will be treated as 
>> "private."  Combined with treaing all names in __all__ as locally 
>> defined, this might do what you want.  Alternatively, you might 
>> consider renaming wx.core to wx._core (which will make it very clear 
>> to your users that it's an implementation module, and shouldnt be used 
>> directly).
> 
> 
> 
> Ah, thanks, it makes sense now.  For some reason a couple synapses were 
> not making the connection before.  Now I know how some of my users feel 
> when I point out the obvious to them!  ;-)
> 

In case anybody else is reading this besides Edward and myself, I've 
just attached a patch for implementing this to the RFE:

http://sourceforge.net/tracker/index.php?func=detail&aid=938924&group_id=32455&atid=405621

Works great on wxPython and didn't seem to cause any problems on the 
other tests I threw at it.

-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!

Re: [Epydoc-devel] Re: epydoc questions

[Robin D. <ro...@al...>]

Edward Loper wrote:
> Robin Dunn wrote:
> 
>>> But I'm sure you don't want *all* imported objects to be listed as if 
>>> they're defined locally.
>>
>>
>> Actually, in this case I do want all of them. 
> 
> 
> For this one module, maybe, but not in general, right?  So maybe what 
> you want is a module-level way of saying "treat imported objects as 
> locally defined" instead of an object-level one?
> 
>> For the docs my preference would be that "core" and "wx.core" does not 
>> show up anywhere, and that everything that lives in wx.core would just 
>> be documented as "wx.Whatever".
> 
> 
> If "core" isn't listed in wx.__all__, then it will be treated as 
> "private."  Combined with treaing all names in __all__ as locally 
> defined, this might do what you want.  Alternatively, you might consider 
> renaming wx.core to wx._core (which will make it very clear to your 
> users that it's an implementation module, and shouldnt be used directly).


Ah, thanks, it makes sense now.  For some reason a couple synapses were 
not making the connection before.  Now I know how some of my users feel 
when I point out the obvious to them!  ;-)

-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!

Re: [Epydoc-devel] Re: epydoc questions

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

Robin Dunn wrote:
>> But I'm sure you don't want *all* imported objects to be listed as if 
>> they're defined locally.
> 
> Actually, in this case I do want all of them. 

For this one module, maybe, but not in general, right?  So maybe what 
you want is a module-level way of saying "treat imported objects as 
locally defined" instead of an object-level one?

> For the docs my preference would be that "core" and "wx.core" does not 
> show up anywhere, and that everything that lives in wx.core would just 
> be documented as "wx.Whatever".

If "core" isn't listed in wx.__all__, then it will be treated as 
"private."  Combined with treaing all names in __all__ as locally 
defined, this might do what you want.  Alternatively, you might consider 
renaming wx.core to wx._core (which will make it very clear to your 
users that it's an implementation module, and shouldnt be used directly).

>> So epydoc needs some information source to decide which imported 
>> objects  it should pretend are defined locally.
>>
>> One option is to use __all__.  In particular, any imported objects 
>> listed in __all__ will be treated as if they were defined locally.
> 
> With hundreds of objects per module that gets to be a little difficult 
> to maintain...  I'll keep it in mind though.

There's no reason that __all__ has to be defined using a list literal. 
In particular, you might consider doing something like this:

     # Import all objects from wx.core (the implementation module)
     from wx.core import *

     # Declare that all of the objects imported from wx.core are public
     import wx.core
     __all__ += [name for name in dir(wx.core)
                 if not name.startswith('__') and name.endswith('__')]
     del wx.core

>> Another option is to define a new field for the module docstring, that 
>> declares that an object should be treated as if it was defined 
>> locally.  Something like "@local: Window", although I'm not crazy 
>> about that name.
> 
> This too.

@local would presumably support the "*" syntax that's supported by 
@group, @sort, and @undefined.  In particular, you could just do:

     @local: *

I think I like the __all__ solution better, though.

-Edward

Re: [Epydoc-devel] Re: epydoc questions

[Robin D. <ro...@al...>]

Edward Loper wrote:
>
>> And if I decide that I am insane enough <wink!> to try and implement 
>> the above feature on the current system do you have any suggestions 
>> for how to go about doing it?
> 
> 
> So basically you want some of the imported objects (eg wx.core.Window) 
> to be treated as if they were defined locally.  

Yes.

> But I'm sure you don't 
> want *all* imported objects to be listed as if they're defined locally.

Actually, in this case I do want all of them. The wx.core and a few 
other modules are really just implementation details that are required 
because some C/C++ compilers start to choke when compiling files more 
than about 60K lines of code, and because SWIG can't split a single 
extension module across multiple C files.

For the docs my preference would be that "core" and "wx.core" does not 
show up anywhere, and that everything that lives in wx.core would just 
be documented as "wx.Whatever".

> 
> So epydoc needs some information source to decide which imported objects 
>  it should pretend are defined locally.
> 
> One option is to use __all__.  In particular, any imported objects 
> listed in __all__ will be treated as if they were defined locally.

With hundreds of objects per module that gets to be a little difficult 
to maintain...  I'll keep it in mind though.

> 
> Another option is to define a new field for the module docstring, that 
> declares that an object should be treated as if it was defined locally. 
>  Something like "@local: Window", although I'm not crazy about that name.

This too.

> 
> In either case, you would modify ModuleDoc.__init__ and 
> ModuleDoc._find_imported_variables, to treat the desired values as 
> non-imported (i.e., add them to self._x instead of self._imported_x).

Yep, I discovered that bit in the code shortly after sending the prior 
message, and I have been experimenting a bit since then.  Nothing is 
really working yet, but at least I'm getting very familiar with the code ;-)

-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!

Re: [Epydoc-devel] Re: epydoc questions

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

>> This would be hard to do with the current system.  But it should 
>> become easier after I make some of the architectural changes I mentioned.
> 
> Is there anything written about this new architecture that I could 
> review?  

It's pretty preliminary right now.  Once I get a little further along, 
I'll write up a description/explanation, but right now I'm trying to 
figure out exactly how I want it to look.  Some of the motivations 
behind it are...
   - better support for extracting docs via source code parsing
   - plug-in support for extending epydoc (eg there will be a zope
     plug-in that handles zope interfaces, etc.)
   - more consistent & flexible handling of object names.

At some point, I should write up a description & an an explination of 
what's motivating it, but I haven't had a chance yet.  I just checked 
some of my preliminary work in to cvs:

     epydoc/sandbox/epydoc3/epydoc/*

But at this point, it doesn't do much.

> Is there an ETA?  

At least a month, maybe more.  (I don't get as much time to work on 
epydoc as I'd like).

> And if I decide that I am insane enough 
> <wink!> to try and implement the above feature on the current system do 
> you have any suggestions for how to go about doing it?

So basically you want some of the imported objects (eg wx.core.Window) 
to be treated as if they were defined locally.  But I'm sure you don't 
want *all* imported objects to be listed as if they're defined locally.

So epydoc needs some information source to decide which imported objects 
  it should pretend are defined locally.

One option is to use __all__.  In particular, any imported objects 
listed in __all__ will be treated as if they were defined locally.

Another option is to define a new field for the module docstring, that 
declares that an object should be treated as if it was defined locally. 
  Something like "@local: Window", although I'm not crazy about that name.

In either case, you would modify ModuleDoc.__init__ and 
ModuleDoc._find_imported_variables, to treat the desired values as 
non-imported (i.e., add them to self._x instead of self._imported_x).

-Edward

[Epydoc-devel] Re: epydoc questions

[Robin D. <ro...@al...>]

Edward Loper wrote:
> Robin Dunn wrote:
> 
[...]
>> * Using the new wx package several of the core submodules are imported 
>> into the package namespace so the programmer doesn't have to worry 
>> about explicitly importing those submodules.  For example, instead of 
>> using wx.core.Window the programmer will just use wx.Window.  Is there 
>> any trick you can think of to make epydoc document the objects in 
>> those submodules as if they were actually in wx itself?  That way the 
>> reader of the docs still won't have to know anything about the 
>> implementation details and the docs will accurately reflect how it is 
>> supposed to be used.
> 
> 
> This would be hard to do with the current system.  But it should become 
> easier after I make some of the architectural changes I mentioned.

Hi Edward,

Is there anything written about this new architecture that I could 
review?  Is there an ETA?  And if I decide that I am insane enough 
<wink!> to try and implement the above feature on the current system do 
you have any suggestions for how to go about doing it?


-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!