epydoc-devel

[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/

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