[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

[patch] python docstring generation with swig through doxygen

From: Leo Simons <mail_at_leosimons.com>
Date: 2005-03-29 02:15:49 CEST

Hi gang!

Please CC me on replies as I'm not subscribed to this list.

I'm not sure if you've seen it yet, but someone has written a script
doxy2swig.py [1] that takes a doxygen-generated xml file and transforms
it into a swig interface file that contains docstring declarations for
python [2].

I had a go at running this over the subversion codebase. The attached
patch fixes all "&" used in comments to be "&amp;", so that the xml
doxygen generates is actually valid xml and the subsequent parsing
stages can succeed (which might be a good idea to apply anyway...). It
then also modifies doxygen.conf to actually output xml...

Combined with the script mentioned above (which I didn't include in the
patch as I'm not sure about license bla bla bla) and xsltproc (apt-get
install xsltproc bla bla), you can do something like:

cd ~/svn/svn/trunk
doxygen doc/doxygen.conf
cd doc/doxygen/xml
xsltproc combine.xslt index.xml >all.xml
wget http://www.ae.iitm.ac.in/~prabhu/software/code/python/doxy2swig.py
python doxy2swig.py all.xml all.docstrings.i

running the python command consumes quite a few resources; be patient.
This results in a file all.docstrings.i that, IIUC, could be %include d
in some way from the swig *.i files. Having just learned my first bits
of SWIG just now, that's where I failed to figure out how to proceed.

It would be very cool if someone would be able to take a look and
perhaps take this further; perhaps integrating it into the buildsystem
(which is also well beyond me ;). It would allow stuff like

>>> from svn import fs
>>> fs.__doc__
   <<meaningful output now appears here>>

as well as providing that documentation in IDEs such as Wing. Which,
neadless to say, is very useful if you're sold on python+svn but not
quite as confortable reading C source, which is why I attempted all this
in the first place :-D

Finally note that this only works with bleeding edge (1.3.23+) swig, at
least that what the docs say.


Leo Simons

[1] -- http://www.ae.iitm.ac.in/~prabhu/software/python.html
[2] -- http://www.swig.org/Doc1.3/Python.html#Python_nn65

Index: subversion/libsvn_fs_base/tree.c
--- subversion/libsvn_fs_base/tree.c (revision 13730)
+++ subversion/libsvn_fs_base/tree.c (working copy)
@@ -2067,7 +2067,7 @@
    * && (! T ancestorof S))
    * See the following message for the full details:
- * http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgId=166183 */
+ * http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgId=166183 */
   if ((svn_fs_base__dag_node_kind (source) != svn_node_dir)
       || (svn_fs_base__dag_node_kind (target) != svn_node_dir)
Index: subversion/libsvn_fs_base/fs.c
--- subversion/libsvn_fs_base/fs.c (revision 13730)
+++ subversion/libsvn_fs_base/fs.c (working copy)
@@ -416,7 +416,7 @@
     "# will hurt commit performance. For details, see this post from\n"
     "# Daniel Berlin <dan@dberlin.org>:\n"
- "# http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgId=161960\n"
+ "# http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgId=161960\n"
     "set_lg_bsize 262144\n"
     "set_lg_max 1048576\n"
Index: subversion/include/svn_xml.h
--- subversion/include/svn_xml.h (revision 13730)
+++ subversion/include/svn_xml.h (working copy)
@@ -133,7 +133,7 @@
  * representable, except for most ASCII control characters (the
  * exceptions being CR, LF, and TAB, which are valid in XML). There
  * may be other UTF-8 characters that are invalid in XML; see
- * http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=90591
+ * http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgNo=90591
  * and its thread for details.
 const char *svn_xml_fuzzy_escape (const char *string,
Index: subversion/include/svn_types.h
--- subversion/include/svn_types.h (revision 13730)
+++ subversion/include/svn_types.h (working copy)
@@ -221,7 +221,7 @@
  * would take care of both internationalization issues and custom
  * keywords (e.g., $NetBSD$). See
- *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921
+ *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgNo=8921
  * =====
  * From: "Jonathan M. Manning" <jmanning@alisa-jon.net>
  * To: dev@subversion.tigris.org
@@ -231,7 +231,7 @@
  * and Eric Gillespie's support of same:
- *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757
+ *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgNo=8757
  * =====
  * From: "Eric Gillespie, Jr." <epg@pretzelnet.org>
  * To: dev@subversion.tigris.org
Index: subversion/libsvn_subr/io.c
--- subversion/libsvn_subr/io.c (revision 13730)
+++ subversion/libsvn_subr/io.c (working copy)
@@ -2505,7 +2505,7 @@
      relies on those guarantees). Unfortunately apr_dir_read doesn't
      work that way in practice, in particular ext3 on Linux-2.6 doesn't
      follow the rules. For details see
- http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=56666 for
+ http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgNo=56666 for
      If APR ever does implement "dot-first" then it would be possible to
      remove the svn_io_stat and walk_func calls and use the walk_func
Index: subversion/tests/libsvn_diff/diff-diff3-test.c
--- subversion/tests/libsvn_diff/diff-diff3-test.c (revision 13730)
+++ subversion/tests/libsvn_diff/diff-diff3-test.c (working copy)
@@ -1496,7 +1496,7 @@
 /* Merge is more "aggressive" about resolving conflicts than traditional
  * patch or diff3. Some people consider this behaviour to be a bug, see
- * http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=35014
+ * http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgNo=35014
 static svn_error_t *
 merge_adjacent_changes (const char **msg,
Index: subversion/tests/clients/cmdline/stat_tests.py
--- subversion/tests/clients/cmdline/stat_tests.py (revision 13730)
+++ subversion/tests/clients/cmdline/stat_tests.py (working copy)
@@ -372,7 +372,7 @@
   # See this thread:
- # http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=27975
+ # http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgNo=27975
   # Basically, Andreas was seeing inconsistent results depending on
   # whether or not he accompanied 'svn status -u' with '-v':
Index: doc/doxygen.conf
--- doc/doxygen.conf (revision 13730)
+++ doc/doxygen.conf (working copy)
@@ -860,7 +860,7 @@
 # generate an XML file that captures the structure of
 # the code including all documentation.
 # The XML_OUTPUT tag is used to specify where the XML pages will be put.
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be
@@ -885,7 +885,7 @@
 # and cross-referencing information) to the XML output. Note that
 # enabling this will significantly increase the size of the XML output.
 # configuration options for the AutoGen Definitions output

To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Mar 30 05:14:26 2005

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.