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

>  (Rick) If Doxygen works for you, that's great.

Doxygen does _not_ work for me (I thought I made that clear). The 
translation to pseudo-C++ is a nonstarter.

>  (Stefan) I'm honestly not quite sure I understand what you are looking for.

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.

Our Python code (grtumble) is not in Packages. It's in directory 
hierarchies. 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 ;-(

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.

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.

>  (Stefan) How does this python-to-pseudo-C++ converter work ?
>  How *can* it work ?

It does its best.
The filter transforms Python code into C++ stubs
http://i31www.ira.uka.de/~baas/pydoxy/#example

	foo.bar.baz
becomes
	foo::bar::baz

	import foo
becomes
	#include foo

	def foo(self, bar):
becomes
	foo(bar);

it gets weird.

>  (Stefan) Are you working with python ? With C++ ? With multiple languages ?

Our engineers are writing in Python. Doxygen is working with C++. The 
filter tries to bring the two into alignment. It actually (almost) 
does a spectacular job.

The weirdest part is that the fake C++ is what you _see_ in the 
results. That's what kills Doxygen for me. If it used the fake C++ 
stubs to build its trees and such and then showed the {Python, I 
could be convinced. But what I see in the results bears no relation 
to the original code :-(

I want the sorts of results Doxygen presents and I want them for a 
full tree of related, inter-imported soource files that together make 
up a single executable.

Sigh.
>--__--__--
>
>Message: 6
>From: Stefan Seefeld <[email protected]>
>To: "'[email protected]'" <[email protected]>
>Date: Tue, 21 Dec 2004 14:21:32 -0500
>Subject: RE: [Synopsis-devel] Re: Can synopsis (be made to) follow Python
>	imports?
>Reply-To: [email protected]
>
>>  From: Vicki Brown [mailto:[email protected]]
>
>>  The only drawback is that, in order to make Doxygen work on Python, I
>>  have to cause it to run the source code through a filter that
>>  converts all of the Python source to pseudo-C++. The results are
>>  very much what I want to see. Extremely complete and extensive. But
>>  all of the source 'looks" like C++ :-(
>
>How does this python-to-pseudo-C++ converter work ? How *can* it work ?
>C++ is a statically typed language where types and variables are declared.
>Python is dynamic.
>
>Is there any place where I can see an example of such 'cross referenced
>python' ?
>
>I'm honestly not quite sure I understand what you are looking for. Are
>you working with python ? With C++ ? With multiple languages ?
>
>Regards,
>		Stefan
>
>

>Date: Tue, 21 Dec 2004 14:37:23 -0800
>From: Richard Kelly <[email protected]>
>
>I am not criticizing Doxygen here.  Doxygen is a fine product, and it
>can do a lot for you.  However, we've had to muck with it A LOT in order
>to generate our Python docs.  Our solution works well enough, but it's
>fragile and difficult to maintain.  It's certainly not something we're
>proud of.  We are experimenting with Synopsis now, because we think
>it'll provide a better alternative than Doxygen.  The jury's still out,
>but at the moment Synopsis looks like it'll work much better for us than
>does Doxygen.
>
>>  The only drawback is that, in order to make Doxygen work on Python, I
>>  have to cause it to run the source code through a filter that
>>  converts all of the Python source to pseudo-C++. The results are very
>>  much what I want to see. Extremely complete and extensive. But all of
>>  the source 'looks" like C++ :-(
>
>If Doxygen works for you, that's great.  As I said, it's a fine product.
>   However, I'd caution you first to spend A LOT of time testing your
>Python->C++ converter.  You're going to have to live with it for a long
>time, and there may be numerous hidden gotchas.
>
>Rick
>--
>Richard M Kelly                             [email protected]
>[PGP  =>  D5 C3 CC D2 B7 D0 A9 B0  D5 90 B2 55 5A 80 23 B6  FC AB 67 B4]
>
>
>
>--__--__--
>
>_______________________________________________
>Synopsis-devel mailing list
>[email protected]
>http://lists.fresco.org/cgi-bin/listinfo/synopsis-devel
>
>
>End of Synopsis-devel Digest

-- 
- V.
Vicki Brown <[email protected]> * Jabber: [email protected]
   Software Development Internal Technical Documentation
   http://www.cfcl.com/vlb/Jobweb/