2.5.1p5 preview release

Robin · December 24, 2003, 6:27am

Hi all,

Just in time to tuck it under your Christmas tree, I've just made another preview snapshot of wxPython 2.5.1, it is availabe at

http://alldunn.com/wxPython/preview/2.5.x/wxPythonWIN32-preview-2.5.1p5.tar.gz

Just like the last one, this is only a quickie tarball of the Win32 Python 2.3 version of wxPython, there is no installer. Just unpack the archive somewhere like c:\ and then you can use it without disturbing your 2.4 install simply by setting PYTHONPATH to c:\wxPython-2.5.1p5.

Thanks mostly to Jeff G. the demo and most of the lib has been converted to the new wx namespace. If you run into any problems related to that please let us know.

Other changes since the last preview include improved generation of the automatic docstrings, generation of XML metadata that can be used for generating the refernce docs (see below) many of the bugs that were reported with the last preview as well as several others I've found along the way.

The metadata is located in docs/xml/wxPython-metadata.xml. It needs a bit more refinement in the content (some things still need converting to new names, etc.) but I think the basic structure is all set. Most parts of the data should be self explainitory, but here are a few notes:

* There are up to three types of documentation that can be attached to items. <autodoc> is what is either what is generated by my SWIG modifications, or is explicitly specified in the .i files and is the definition of the parameter types of functions or methods. <docstring> is the short description of items that are specified in the .i files. The autodoc + docstring are what is put into the .py files as the docstring of the items. The third docstring type is <refdoc> and is intended to be used for the detailed docs that will only show up in the reference docs. There are currently only a few <docstring>'s and very few <refdoc>'s as I've been working more on tools and structure, but they'll start coming soon.

* The content of the <pythoncode> elements are directly copied from the %pythoncode directives in the .i files, and they are also written to the .py files. I included it in the metadata "just in case" but since there is no structure there they will probably only be useful if generating a pseudo wx pacakge for runnign epydoc on or something. I would like to find a way to include metadata for things that are added in <pythoncode>'s...

* I included overloaded="yes|no" attributes for functions/methods since I am starting to use SWIG's overloading abilities in a few places. You'll notice that the autodoc for those already includes all of the overloaded signatures.

If there are any questions or suggestions about the XML structure just ask.

Riaan, you had volunteered to do scripting for generating docs. Is there enough info in the metadata file to do what yo had in mind?

I'm sure there was more that I was going to write more here but I'm too tired to think straight so I'm going to quit before I start babbling incoherently...

Happy Holidays all!

···

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

Grimmtooth · December 24, 2003, 3:36pm

Thanks mostly to Jeff G. the demo and most of the lib has been converted
to the new wx namespace. If you run into any problems related to that
please let us know.

BTW, also check
http://wiki.wxpython.org/index.cgi/wxPython_20Third_2dparty_20libraries and
http://wiki.wxpython.org/index.cgi/wxPython_202_2e5_20Demo_20Update_20Status
to see if your issue is listed there.

Kevin_Altis · December 25, 2003, 6:32pm

Sadly Winzip (8.1 and 9.0beta) were unable to open the archive due to the
following error.

"End-of-central-directory signature not found. Either this file is not a
Zip file, or it constitutes one disk of a multi-part Zip file."

The size of the file I downloaded is 21,104,640 bytes. Is the file actually
corrupt or should I try opening it with some other utility?

ka

···

-----Original Message-----
From: Robin Dunn [mailto:robin@alldunn.com]
Sent: Tuesday, December 23, 2003 10:28 PM
To: wxPython-dev@lists.wxwindows.org
Subject: [wxPython-dev] 2.5.1p5 preview release

Hi all,

Just in time to tuck it under your Christmas tree, I've just made
another preview snapshot of wxPython 2.5.1, it is availabe at

http://alldunn.com/wxPython/preview/2.5.x/wxPythonWIN32-preview-2.
5.1p5.tar.gz

Just like the last one, this is only a quickie tarball of the Win32
Python 2.3 version of wxPython, there is no installer. Just unpack the
archive somewhere like c:\ and then you can use it without disturbing
your 2.4 install simply by setting PYTHONPATH to c:\wxPython-2.5.1p5.

Thanks mostly to Jeff G. the demo and most of the lib has been converted
to the new wx namespace. If you run into any problems related to that
please let us know.

Other changes since the last preview include improved generation of the
automatic docstrings, generation of XML metadata that can be used for
generating the refernce docs (see below) many of the bugs that were
reported with the last preview as well as several others I've found
along the way.

The metadata is located in docs/xml/wxPython-metadata.xml. It needs a
bit more refinement in the content (some things still need converting to
new names, etc.) but I think the basic structure is all set. Most parts
of the data should be self explainitory, but here are a few notes:

* There are up to three types of documentation that can be attached to
items. <autodoc> is what is either what is generated by my SWIG
modifications, or is explicitly specified in the .i files and is the
definition of the parameter types of functions or methods. <docstring>
is the short description of items that are specified in the .i files.
The autodoc + docstring are what is put into the .py files as the
docstring of the items. The third docstring type is <refdoc> and is
intended to be used for the detailed docs that will only show up in the
reference docs. There are currently only a few <docstring>'s and very
few <refdoc>'s as I've been working more on tools and structure, but
they'll start coming soon.

* The content of the <pythoncode> elements are directly copied from the
%pythoncode directives in the .i files, and they are also written to the
.py files. I included it in the metadata "just in case" but since there
is no structure there they will probably only be useful if generating a
pseudo wx pacakge for runnign epydoc on or something. I would like to
find a way to include metadata for things that are added in
<pythoncode>'s...

* I included overloaded="yes|no" attributes for functions/methods since
I am starting to use SWIG's overloading abilities in a few places.
You'll notice that the autodoc for those already includes all of the
overloaded signatures.

If there are any questions or suggestions about the XML structure
just ask.

Riaan, you had volunteered to do scripting for generating docs. Is
there enough info in the metadata file to do what yo had in mind?

I'm sure there was more that I was going to write more here but I'm too
tired to think straight so I'm going to quit before I start babbling
incoherently...

Happy Holidays all!

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

Grimmtooth · December 25, 2003, 7:38pm

I had similar problems last time with Explorer. I used Firebird and was able
to get the file intact, then WinZip didn't have an probs with it.

···

-----Original Message-----
From: Kevin Altis [mailto:altis@semi-retired.com]
Sent: Thursday, December 25, 2003 13:33
To: wxPython-dev@lists.wxwindows.org
Subject: RE: [wxPython-dev] 2.5.1p5 preview release

Sadly Winzip (8.1 and 9.0beta) were unable to open the archive due to the
following error.

"End-of-central-directory signature not found. Either this file is not a
Zip file, or it constitutes one disk of a multi-part Zip file."

The size of the file I downloaded is 21,104,640 bytes. Is the
file actually
corrupt or should I try opening it with some other utility?

ka

> -----Original Message-----
> From: Robin Dunn [mailto:robin@alldunn.com]
> Sent: Tuesday, December 23, 2003 10:28 PM
> To: wxPython-dev@lists.wxwindows.org
> Subject: [wxPython-dev] 2.5.1p5 preview release
>
>
> Hi all,
>
> Just in time to tuck it under your Christmas tree, I've just made
> another preview snapshot of wxPython 2.5.1, it is availabe at
>
> http://alldunn.com/wxPython/preview/2.5.x/wxPythonWIN32-preview-2.
> 5.1p5.tar.gz
>
> Just like the last one, this is only a quickie tarball of the Win32
> Python 2.3 version of wxPython, there is no installer. Just unpack the
> archive somewhere like c:\ and then you can use it without disturbing
> your 2.4 install simply by setting PYTHONPATH to c:\wxPython-2.5.1p5.
>
> Thanks mostly to Jeff G. the demo and most of the lib has been converted
> to the new wx namespace. If you run into any problems related to that
> please let us know.
>
> Other changes since the last preview include improved generation of the
> automatic docstrings, generation of XML metadata that can be used for
> generating the refernce docs (see below) many of the bugs that were
> reported with the last preview as well as several others I've found
> along the way.
>
> The metadata is located in docs/xml/wxPython-metadata.xml. It needs a
> bit more refinement in the content (some things still need converting to
> new names, etc.) but I think the basic structure is all set. Most parts
> of the data should be self explainitory, but here are a few notes:
>
> * There are up to three types of documentation that can be attached to
> items. <autodoc> is what is either what is generated by my SWIG
> modifications, or is explicitly specified in the .i files and is the
> definition of the parameter types of functions or methods. <docstring>
> is the short description of items that are specified in the .i files.
> The autodoc + docstring are what is put into the .py files as the
> docstring of the items. The third docstring type is <refdoc> and is
> intended to be used for the detailed docs that will only show up in the
> reference docs. There are currently only a few <docstring>'s and very
> few <refdoc>'s as I've been working more on tools and structure, but
> they'll start coming soon.
>
> * The content of the <pythoncode> elements are directly copied from the
> %pythoncode directives in the .i files, and they are also written to the
> .py files. I included it in the metadata "just in case" but since there
> is no structure there they will probably only be useful if generating a
> pseudo wx pacakge for runnign epydoc on or something. I would like to
> find a way to include metadata for things that are added in
> <pythoncode>'s...
>
> * I included overloaded="yes|no" attributes for functions/methods since
> I am starting to use SWIG's overloading abilities in a few places.
> You'll notice that the autodoc for those already includes all of the
> overloaded signatures.
>
> If there are any questions or suggestions about the XML structure
> just ask.
>
> Riaan, you had volunteered to do scripting for generating docs. Is
> there enough info in the metadata file to do what yo had in mind?
>
> I'm sure there was more that I was going to write more here but I'm too
> tired to think straight so I'm going to quit before I start babbling
> incoherently...
>
> Happy Holidays all!
>
> --
> Robin Dunn
> Software Craftsman
> http://wxPython.org Java give you jitters? Relax with wxPython!

---------------------------------------------------------------------
To unsubscribe, e-mail: wxPython-dev-unsubscribe@lists.wxwindows.org
For additional commands, e-mail: wxPython-dev-help@lists.wxwindows.org

Kevin_Altis · December 25, 2003, 8:01pm

Thanks. I just downloaded it with python (urllib...) and the file is
readable; the actual size is 5,836,585 bytes. The server Robin is running
must not like IE 6.x I guess. The server reports that it is Apache, but
since there isn't a version number it doesn't look like a normal Apache
"Server:" id. Anyway, something is going wrong to cause the downloaded file
to be significantly larger than it should be.

HTTP/1.1 200 OK
Server: Apache
Last-Modified: Wed, 24 Dec 2003 03:00:30 GMT
ETag: "17c03d-590f29-3fe9014e"
Accept-Ranges: bytes
Content-Length: 5836585
Connection: close
Content-Type: application/x-gunzip
Content-Encoding: x-gzip

ka

···

Date: Thu, 25 Dec 2003 19:57:20 GMT

-----Original Message-----
From: Jeff Grimmett [mailto:grimmtooth@softhome.net]
Sent: Thursday, December 25, 2003 11:38 AM
To: wxPython-dev@lists.wxwindows.org
Subject: RE: [wxPython-dev] 2.5.1p5 preview release

I had similar problems last time with Explorer. I used Firebird
and was able
to get the file intact, then WinZip didn't have an probs with it.

> -----Original Message-----
> From: Kevin Altis [mailto:altis@semi-retired.com]
> Sent: Thursday, December 25, 2003 13:33
> To: wxPython-dev@lists.wxwindows.org
> Subject: RE: [wxPython-dev] 2.5.1p5 preview release
>
>
> Sadly Winzip (8.1 and 9.0beta) were unable to open the archive
due to the
> following error.
>
> "End-of-central-directory signature not found. Either this
file is not a
> Zip file, or it constitutes one disk of a multi-part Zip file."
>
> The size of the file I downloaded is 21,104,640 bytes. Is the
> file actually
> corrupt or should I try opening it with some other utility?
>
> ka
>
> > -----Original Message-----
> > From: Robin Dunn [mailto:robin@alldunn.com]
> > Sent: Tuesday, December 23, 2003 10:28 PM
> > To: wxPython-dev@lists.wxwindows.org
> > Subject: [wxPython-dev] 2.5.1p5 preview release
> >
> >
> > Hi all,
> >
> > Just in time to tuck it under your Christmas tree, I've just made
> > another preview snapshot of wxPython 2.5.1, it is availabe at
> >
> > http://alldunn.com/wxPython/preview/2.5.x/wxPythonWIN32-preview-2.
> > 5.1p5.tar.gz
> >
> > Just like the last one, this is only a quickie tarball of the Win32
> > Python 2.3 version of wxPython, there is no installer. Just
unpack the
> > archive somewhere like c:\ and then you can use it without disturbing
> > your 2.4 install simply by setting PYTHONPATH to c:\wxPython-2.5.1p5.
> >
> > Thanks mostly to Jeff G. the demo and most of the lib has
been converted
> > to the new wx namespace. If you run into any problems related to that
> > please let us know.
> >
> > Other changes since the last preview include improved
generation of the
> > automatic docstrings, generation of XML metadata that can be used for
> > generating the refernce docs (see below) many of the bugs that were
> > reported with the last preview as well as several others I've found
> > along the way.
> >
> > The metadata is located in docs/xml/wxPython-metadata.xml. It needs a
> > bit more refinement in the content (some things still need
converting to
> > new names, etc.) but I think the basic structure is all set.
Most parts
> > of the data should be self explainitory, but here are a few notes:
> >
> > * There are up to three types of documentation that can be attached to
> > items. <autodoc> is what is either what is generated by my SWIG
> > modifications, or is explicitly specified in the .i files and is the
> > definition of the parameter types of functions or methods.
<docstring>
> > is the short description of items that are specified in the .i files.
> > The autodoc + docstring are what is put into the .py files as the
> > docstring of the items. The third docstring type is <refdoc> and is
> > intended to be used for the detailed docs that will only show
up in the
> > reference docs. There are currently only a few <docstring>'s and very
> > few <refdoc>'s as I've been working more on tools and structure, but
> > they'll start coming soon.
> >
> > * The content of the <pythoncode> elements are directly
copied from the
> > %pythoncode directives in the .i files, and they are also
written to the
> > .py files. I included it in the metadata "just in case" but
since there
> > is no structure there they will probably only be useful if
generating a
> > pseudo wx pacakge for runnign epydoc on or something. I would like to
> > find a way to include metadata for things that are added in
> > <pythoncode>'s...
> >
> > * I included overloaded="yes|no" attributes for
functions/methods since
> > I am starting to use SWIG's overloading abilities in a few places.
> > You'll notice that the autodoc for those already includes all of the
> > overloaded signatures.
> >
> > If there are any questions or suggestions about the XML structure
> > just ask.
> >
> > Riaan, you had volunteered to do scripting for generating docs. Is
> > there enough info in the metadata file to do what yo had in mind?
> >
> > I'm sure there was more that I was going to write more here
but I'm too
> > tired to think straight so I'm going to quit before I start babbling
> > incoherently...
> >
> > Happy Holidays all!
> >
> > --
> > Robin Dunn
> > Software Craftsman
> > http://wxPython.org Java give you jitters? Relax with wxPython!
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: wxPython-dev-unsubscribe@lists.wxwindows.org
> For additional commands, e-mail: wxPython-dev-help@lists.wxwindows.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: wxPython-dev-unsubscribe@lists.wxwindows.org
For additional commands, e-mail: wxPython-dev-help@lists.wxwindows.org

Grimmtooth · December 25, 2003, 9:38pm

must not like IE 6.x I guess. The server reports that it is Apache, but
since there isn't a version number it doesn't look like a normal Apache
"Server:" id. Anyway, something is going wrong to cause the
downloaded file to be significantly larger than it should be.

Yep, exactly what happened to me the last two times. In a wierd way I'm
glad I'm not the only one seeing this problem

Robin · December 26, 2003, 5:22pm

Kevin Altis wrote:

Thanks. I just downloaded it with python (urllib...) and the file is
readable; the actual size is 5,836,585 bytes. The server Robin is running
must not like IE 6.x I guess. The server reports that it is Apache, but
since there isn't a version number it doesn't look like a normal Apache
"Server:" id. Anyway, something is going wrong to cause the downloaded file
to be significantly larger than it should be.

IIRC, IE will by default interpret files with a .gz extension to be some streamable media format and it ignores the Content-type header, or something like that. There is probably something that can be done on the server and/or the client to correct this, but I don't remember what it is... I'll just change the file to a .tgz extension and that should solve it too.

···

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

Kevin_Altis · December 27, 2003, 6:27pm

Just wondering if you are going to do builds for Mac OS X and Linux? Mostly
I'm curious about the Mac, but only if wxSTC has been fixed so that
anti-aliasing doesn't make it unusable.

I'm not running Panther yet, so just an old style build would do. I guess
the problem is that it is more difficult to drop the packages onto a
PYTHONPATH and leave the old 2.4.x stuff alone?

ka

Kevin_Ollivier4 · December 27, 2003, 5:36pm

Hi Kevin (A),

Just wondering if you are going to do builds for Mac OS X and Linux? Mostly
I'm curious about the Mac, but only if wxSTC has been fixed so that
anti-aliasing doesn't make it unusable.

The Mac version of 2.5.1 has performance improvements around the board, and particularly in wxSTC. It is quite usable now. =)

I'm not running Panther yet, so just an old style build would do. I guess
the problem is that it is more difficult to drop the packages onto a
PYTHONPATH and leave the old 2.4.x stuff alone?

I am running Panther, else I would volunteer to put up a build here. There's supposedly a way to build backwards compatible builds, but I haven't figured out how to do so yet.

People would have to manually set/change the path values to keep multiple versions on one machine, but we could make the installer work so that it put things into a separate place, at least on Mac.

Thanks,

Kevin

···

On Dec 27, 2003, at 1:27 PM, Kevin Altis wrote:

Kevin_Altis · December 27, 2003, 6:59pm

From: Robin Dunn

Kevin Altis wrote:
> Thanks. I just downloaded it with python (urllib...) and the file is
> readable; the actual size is 5,836,585 bytes. The server Robin
is running
> must not like IE 6.x I guess. The server reports that it is Apache, but
> since there isn't a version number it doesn't look like a normal Apache
> "Server:" id. Anyway, something is going wrong to cause the
downloaded file
> to be significantly larger than it should be.

IIRC, IE will by default interpret files with a .gz extension to be some
streamable media format and it ignores the Content-type header, or
something like that. There is probably something that can be done on
the server and/or the client to correct this, but I don't remember what
it is... I'll just change the file to a .tgz extension and that should
solve it too.

I haven't run a HTTP debug tool to see what headers SourceForge sends when
you download a file from their servers like...

http://prdownloads.sourceforge.net/wxpython/wxPythonDemo-2.4.2.4.tar.gz?down
load

...but I have never had a problem downloading a tar.gz from them. Maybe they
don't send headers like your server?!

Content-Type: application/x-gunzip
Content-Encoding: x-gzip

ka

Riaan_Booysen · December 29, 2003, 1:29pm

Hi Robin,

Robin Dunn wrote:

If there are any questions or suggestions about the XML structure just ask.

Looks nice!

Riaan, you had volunteered to do scripting for generating docs. Is there enough info in the metadata file to do what yo had in mind?

I don't actually have anything in mind I volunteered for something
you have in mind. Hopefully there will be overlap between the
"type library" interface I'll use for in the Boa wrappers some time in
the future and the documentation scripts.

Please tell me what you want for the docs, I don't have any preference
tools or libraries so it's your call.

Cheers,
Riaan.

Chris_Barker1 · December 29, 2003, 6:30pm

Me too! I don't mind building the Linux (or the OS-X either, if setup.y works) version myself, but I need instructions on how to get the right version from CVS, or better yet, a tarball.

-Chris

···

On Dec 27, 2003, at 1:27 PM, Kevin Altis wrote:

Just wondering if you are going to do builds for Mac OS X and Linux?

--
Christopher Barker, Ph.D.
Oceanographer

NOAA/OR&R/HAZMAT (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

Robin · December 29, 2003, 8:38pm

Kevin Altis wrote:

Just wondering if you are going to do builds for Mac OS X and Linux?

I havn't done preview builds for them yet as I didn't want to have to worry about updating the installer and RPM scripts yet, plus compiler tools are freely available on those platforms so people can easily build their own copy. Once I turn my attention to updating the installers for all three platforms then I'll do preview builds for all of them.

Mostly
I'm curious about the Mac, but only if wxSTC has been fixed so that
anti-aliasing doesn't make it unusable.

As Kevin O. mentioned, it is lots better, but it can still be even more better once I implement the fractional text measuring API for the various platforms.

I'm not running Panther yet, so just an old style build would do. I guess
the problem is that it is more difficult to drop the packages onto a
PYTHONPATH and leave the old 2.4.x stuff alone?

It's possible, (as that's how I run my development builds,) but you would need to run everything from the Terminal command line. All the stuff installed to /Applications and such would still want to use the installed 2.4 version.

···

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

Robin · December 29, 2003, 8:39pm

Chris Barker wrote:

···

On Dec 27, 2003, at 1:27 PM, Kevin Altis wrote:

Just wondering if you are going to do builds for Mac OS X and Linux?

Me too! I don't mind building the Linux (or the OS-X either, if setup.y works) version myself, but I need instructions on how to get the right version from CVS, or better yet, a tarball.

Development is happening on the HEAD branch of CVS (aka the main trunk) so a regular cvs update should get it for you. If you previously had a branch checked out (or just want to be sure) then use the -A update flag to ensure that the sticky tags are removed. Instructions for how I build development versions are in .../wxPython/docs/BUILD.devel.txt.

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

Robin · December 29, 2003, 8:41pm

Riaan Booysen wrote:

Hi Robin,

Robin Dunn wrote:

If there are any questions or suggestions about the XML structure just ask.

Looks nice!

Riaan, you had volunteered to do scripting for generating docs. Is there enough info in the metadata file to do what yo had in mind?

I don't actually have anything in mind I volunteered for something
you have in mind. Hopefully there will be overlap between the
"type library" interface I'll use for in the Boa wrappers some time in
the future and the documentation scripts.

Please tell me what you want for the docs, I don't have any preference
tools or libraries so it's your call.

I don't have anything definite in mind yet, just some (somewhat nebulous) goals. I'll try to enumerate them here:

* The primary output format should be easy to use HTML, for either a standard browser, or as MS htmlhelp. By easy to use I mean things like one class per page, with cross-links to other classes, has indexes, customizable with css, etc. Other formats (PDF, etc.) should also be possible but not currently a priority. They could either be done with additional metadata converters or perhaps from some intermediate format that is generated before the HTML output. For example, if the metadata is converted first to ReST then that can be converted to HTML and PDF and whatever else that ReST supports.

* There are a couple approaches that I've considered.

1. The metadata could be converted to a pseudo "wx" package with just stubs for classes and functions where each item includes a docstring composed of all three types of doc elements in the metadata, and none of the extra junk in the SWIG generted modules that would just clutter the docs, and then some existing tool (epydoc, etc.) can be used to generate docs from those modules. The only problem that I see with this is that if the existing tool imports the modules there may not be enough info currently in the metadata to actually make them importable (some missing symbols used for default values, etc.) If the existing tool does not import and just uses the Python parse tree then this approach would probably work okay.

2. Or instead of converting to Python the metadata could be converted directly to epytext or ReST documents, (or straight HTML too I suppose) and then converted from there to the desired output formats using the appropriate tool. This puts more work on our metadata converter, but I think that it will have less restrictions.

* The choice of external tool obviously determines what kind of markup should be used in the <refdoc> snippets.

* I would like the python modules in wx/lib and etc. to fit into this documentation scheme somehow. Either a script that generates wxPython-metadata style XML for them too, (that can then be merged into wxPython-metadata.xml) or perhaps they can just be scanned and converted into the target format when the main metadata is converted. Which ever is easiest, but also makes it appear to be part of the same documentation tree.

Sound doable? Any other ideas?

···

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

Riaan_Booysen · January 5, 2004, 9:19am

Hi Robin,

Robin Dunn wrote:

I don't have anything definite in mind yet, just some (somewhat nebulous) goals. I'll try to enumerate them here:

* The primary output format should be easy to use HTML, for either a standard browser, or as MS htmlhelp. By easy to use I mean things like one class per page, with cross-links to other classes, has indexes, customizable with css, etc. Other formats (PDF, etc.) should also be possible but not currently a priority. They could either be done with additional metadata converters or perhaps from some intermediate format that is generated before the HTML output. For example, if the metadata is converted first to ReST then that can be converted to HTML and PDF and whatever else that ReST supports.

* There are a couple approaches that I've considered.

1. The metadata could be converted to a pseudo "wx" package with just stubs for classes and functions where each item includes a docstring composed of all three types of doc elements in the metadata, and none of the extra junk in the SWIG generted modules that would just clutter the docs, and then some existing tool (epydoc, etc.) can be used to generate docs from those modules. The only problem that I see with this is that if the existing tool imports the modules there may not be enough info currently in the metadata to actually make them importable (some missing symbols used for default values, etc.) If the existing tool does not import and just uses the Python parse tree then this approach would probably work okay.

2. Or instead of converting to Python the metadata could be converted directly to epytext or ReST documents, (or straight HTML too I suppose) and then converted from there to the desired output formats using the appropriate tool. This puts more work on our metadata converter, but I think that it will have less restrictions.

* The choice of external tool obviously determines what kind of markup should be used in the <refdoc> snippets.

* I would like the python modules in wx/lib and etc. to fit into this documentation scheme somehow. Either a script that generates wxPython-metadata style XML for them too, (that can then be merged into wxPython-metadata.xml) or perhaps they can just be scanned and converted into the target format when the main metadata is converted. Which ever is easiest, but also makes it appear to be part of the same documentation tree.

Sound doable? Any other ideas?

I'll try to have a look at this soon.

As a first step I'm going to generate a source tree from xml as you
suggested.

Please give me your markup preference, whoever is going to maintain the
markup should make this choice.

I leave the issue of an xml definition for wx.lib to someone else
for now.

Thanks,
Riaan.

Robin · January 16, 2004, 6:02am

Sorry, I just realized that I hadn't answered this message yet. I guess I don't spend enough time in this mail folder...

Riaan Booysen wrote:

Hi Robin,

Robin Dunn wrote:

I don't have anything definite in mind yet, just some (somewhat nebulous) goals. I'll try to enumerate them here:

* The primary output format should be easy to use HTML, for either a standard browser, or as MS htmlhelp. By easy to use I mean things like one class per page, with cross-links to other classes, has indexes, customizable with css, etc. Other formats (PDF, etc.) should also be possible but not currently a priority. They could either be done with additional metadata converters or perhaps from some intermediate format that is generated before the HTML output. For example, if the metadata is converted first to ReST then that can be converted to HTML and PDF and whatever else that ReST supports.

* There are a couple approaches that I've considered.

1. The metadata could be converted to a pseudo "wx" package with just stubs for classes and functions where each item includes a docstring composed of all three types of doc elements in the metadata, and none of the extra junk in the SWIG generted modules that would just clutter the docs, and then some existing tool (epydoc, etc.) can be used to generate docs from those modules. The only problem that I see with this is that if the existing tool imports the modules there may not be enough info currently in the metadata to actually make them importable (some missing symbols used for default values, etc.) If the existing tool does not import and just uses the Python parse tree then this approach would probably work okay.

2. Or instead of converting to Python the metadata could be converted directly to epytext or ReST documents, (or straight HTML too I suppose) and then converted from there to the desired output formats using the appropriate tool. This puts more work on our metadata converter, but I think that it will have less restrictions.

* The choice of external tool obviously determines what kind of markup should be used in the <refdoc> snippets.

* I would like the python modules in wx/lib and etc. to fit into this documentation scheme somehow. Either a script that generates wxPython-metadata style XML for them too, (that can then be merged into wxPython-metadata.xml) or perhaps they can just be scanned and converted into the target format when the main metadata is converted. Which ever is easiest, but also makes it appear to be part of the same documentation tree.

Sound doable? Any other ideas?

I'll try to have a look at this soon.

Have you made any attempts yet?

As a first step I'm going to generate a source tree from xml as you
suggested.

Please give me your markup preference, whoever is going to maintain the
markup should make this choice.

Since it looks like docutils will probably be put into the Python lib in 2.4 that sounds like it would be a good way to go. Especially since epydoc can also render ReST docstrings too.

I leave the issue of an xml definition for wx.lib to someone else
for now.

Ok.

···

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