RE: Re: Can synopsis (be made to) follow Python imports?

> From: Vicki Brown [mailto:[email protected]]

> I want to see the documentation for everything will become a single 
> executable. That means everything in a given directory tree - the 
> subdirs, all of the files, the resuults from "import" statements (at 
> least the local files) - all in one big gemisch. I get that from 
> Doxygen.

synopsis is file based, i.e. it parses a file that the user tells
it to parse. As a convenience (and a speedup) it may also parse
included ('header') files in case the language is C/C++/IDL.
Considering imported python modules may be possible, I haven't
looked into that. Would you care to submit a feature request to the
tracker (http://synopsis.fresco.org/issues/bug) ?

> Our Python code (grtumble) is not in Packages. It's in directory 
> hierarchies.

For the python interpreter that is (almost) a synonym.

> So Synopsis (and also epydoc) look at a small corner of 
> the code at one directopry level (the set of *.py files I aim them 
> at) and nothing else. Epydoc assumes that a directory == a package. 
> Perhaps Synopsis does too. In our case that's a bad assumption. So, 
> the results document only a fraction of the relevant code and 
> therefore are not of much value ;-(

you can call the 'synopsis' applet specifying a set of files. Or
you can write a 'synopsis.py' script as your custom synopsis driver.
However, to keep synopsis focussed on the actual processing of files,
I didn't work out any logic to let it figure out which files to process.
That's usually better done by the build system the project in question uses.
(Makefiles or equivalent specify how to compile files into object files
and which object files to take to link into executables. The same Makefiles
may be used to define how to generate documentation using a similar 
processing pipeline.)

> What I like about Doxygen - what I want from Synopsis - is that I can 
> aim it at a directory tree with lots of subdirs, lots of files, a 
> bunch of "import statements" in the code - and from there I run 
> Doxygen and it reads _everything in that tree_ from top to bottom.

Yeah, following 'import' statements may be an interesting feature.
Please file an enhancement request.

> The bad news is that Doxygen presents the results looking like C++ 
> which I _can not_ tell our engineers to use. It's just too silly. (If 
> they had wanted to code in C++ they would have done so). The 
> resulting pages are impressive, pretty, and beautifully organized but 
> they're not Python.

For documenting pure python code there already exist a number of good
(python) tools. So I expect that what you are looking for is more a
cross-referencing syntax highlighter that links function calls to
their respective definition. As I said in my last mail, that's quite
hard to get right due to python's dynamic nature. It should, however,
be possible to provide some heuristic tool that guesses what function
is referred to. Is that worth another enhancement request ? :-)

Needless to say: anything will happen so much more quickly as there are
contributors working on it. I'm currently working on C++ code analysis,
but I'd wellcome anybody who has his own ideas where synopsis should head
next !


Regards,
		Stefan