Add Python doxygen example

7 files changed, 380 insertions, 0 deletions

diff --git a/Examples/python/check.list b/Examples/python/check.list
index 73182025d..0798b5f7e 100644
--- a/Examples/python/check.list
+++ b/Examples/python/check.list
@@ -4,6 +4,7 @@ class
 constants
 contract
 docstrings
+doxygen
 enum
 exception
 exceptproxy
diff --git a/Examples/python/doxygen/Makefile b/Examples/python/doxygen/Makefile
new file mode 100644
index 000000000..1a0e3d7c5
--- /dev/null
+++ b/Examples/python/doxygen/Makefile
@@ -0,0 +1,27 @@
+TOP        = ../..
+SWIGEXE    = $(TOP)/../swig
+SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
+CXXSRCS    = example.cxx
+TARGET     = example
+INTERFACE  = example.i
+LIBS       = -lm
+SWIGOPT    = -doxygen
+
+check: build
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' python_run
+
+build:
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \
+	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
+	SWIGOPT='$(SWIGOPT)' \
+	TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' python_cpp
+
+static:
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \
+	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
+	SWIGOPT='$(SWIGOPT)' \
+	TARGET='mypython' INTERFACE='$(INTERFACE)' python_cpp_static
+
+clean:
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' TARGET='$(TARGET)' python_clean
+	rm -f example.html
diff --git a/Examples/python/doxygen/example.cxx b/Examples/python/doxygen/example.cxx
new file mode 100644
index 000000000..ccdb87dfe
--- /dev/null
+++ b/Examples/python/doxygen/example.cxx
@@ -0,0 +1,48 @@
+/* File : example.cxx */
+
+#include "example.h"
+#define M_PI 3.14159265358979323846
+
+/* Move the shape to a new location */
+void Shape::move(double dx, double dy) {
+  x += dx;
+  y += dy;
+}
+
+int Shape::nshapes = 0;
+
+Circle::Circle(double r) : radius(r) {
+  NumCircles++;
+}
+
+double Circle::area() {
+  return M_PI*radius*radius;
+}
+
+double Circle::perimeter() {
+  return 2*M_PI*radius;
+}
+
+Square::Square(double w) : width(w) {
+  NumSquares++;
+}
+
+double Square::area() {
+  return width*width;
+}
+
+double Square::perimeter() {
+  return 4*width;
+}
+
+int NumSquares = 0;
+int NumCircles = 0;
+
+Square MakeSquare(double r) {
+  return Square(r);
+}
+
+Circle MakeCircle(double w) {
+  return Circle(w);
+}
+
diff --git a/Examples/python/doxygen/example.dsp b/Examples/python/doxygen/example.dsp
new file mode 100644
index 000000000..95ad8f173
--- /dev/null
+++ b/Examples/python/doxygen/example.dsp
@@ -0,0 +1,152 @@
+# Microsoft Developer Studio Project File - Name="example" - Package Owner=<4>

+# Microsoft Developer Studio Generated Build File, Format Version 6.00

+# ** DO NOT EDIT **

+

+# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102

+

+CFG=example - Win32 Release

+!MESSAGE This is not a valid makefile. To build this project using NMAKE,

+!MESSAGE use the Export Makefile command and run

+!MESSAGE 

+!MESSAGE NMAKE /f "example.mak".

+!MESSAGE 

+!MESSAGE You can specify a configuration when running NMAKE

+!MESSAGE by defining the macro CFG on the command line. For example:

+!MESSAGE 

+!MESSAGE NMAKE /f "example.mak" CFG="example - Win32 Release"

+!MESSAGE 

+!MESSAGE Possible choices for configuration are:

+!MESSAGE 

+!MESSAGE "example - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")

+!MESSAGE "example - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")

+!MESSAGE 

+

+# Begin Project

+# PROP AllowPerConfigDependencies 0

+# PROP Scc_ProjName ""

+# PROP Scc_LocalPath ""

+CPP=cl.exe

+MTL=midl.exe

+RSC=rc.exe

+

+!IF  "$(CFG)" == "example - Win32 Debug"

+

+# PROP BASE Use_MFC 0

+# PROP BASE Use_Debug_Libraries 1

+# PROP BASE Output_Dir "Debug"

+# PROP BASE Intermediate_Dir "Debug"

+# PROP BASE Target_Dir ""

+# PROP Use_MFC 0

+# PROP Use_Debug_Libraries 1

+# PROP Output_Dir "Debug"

+# PROP Intermediate_Dir "Debug"

+# PROP Ignore_Export_Lib 0

+# PROP Target_Dir ""

+# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c

+# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "$(PYTHON_INCLUDE)" /D "SWIG_PYTHON_INTERPRETER_NO_DEBUG" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c

+# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32

+# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32

+# ADD BASE RSC /l 0x809 /d "_DEBUG"

+# ADD RSC /l 0x809 /d "_DEBUG"

+BSC32=bscmake.exe

+# ADD BASE BSC32 /nologo

+# ADD BSC32 /nologo

+LINK32=link.exe

+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /pdbtype:sept

+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib "$(PYTHON_LIB)" /nologo /dll /debug /machine:I386 /out:"_example.pyd" /pdbtype:sept

+

+!ELSEIF  "$(CFG)" == "example - Win32 Release"

+

+# PROP BASE Use_MFC 0

+# PROP BASE Use_Debug_Libraries 0

+# PROP BASE Output_Dir "Release"

+# PROP BASE Intermediate_Dir "Release"

+# PROP BASE Target_Dir ""

+# PROP Use_MFC 0

+# PROP Use_Debug_Libraries 0

+# PROP Output_Dir "Release"

+# PROP Intermediate_Dir "Release"

+# PROP Ignore_Export_Lib 0

+# PROP Target_Dir ""

+# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c

+# ADD CPP /nologo /MT /W3 /GX /O2 /I "$(PYTHON_INCLUDE)" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c

+# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32

+# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32

+# ADD BASE RSC /l 0x809 /d "NDEBUG"

+# ADD RSC /l 0x809 /d "NDEBUG"

+BSC32=bscmake.exe

+# ADD BASE BSC32 /nologo

+# ADD BSC32 /nologo

+LINK32=link.exe

+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386

+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib "$(PYTHON_LIB)" /nologo /dll /machine:I386 /out:"_example.pyd"

+

+!ENDIF 

+

+# Begin Target

+

+# Name "example - Win32 Debug"

+# Name "example - Win32 Release"

+# Begin Group "Source Files"

+

+# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"

+# Begin Source File

+

+SOURCE=.\example.cxx

+# End Source File

+# Begin Source File

+

+SOURCE=.\example_wrap.cxx

+# End Source File

+# End Group

+# Begin Group "Header Files"

+

+# PROP Default_Filter "h;hpp;hxx;hm;inl"

+# Begin Source File

+

+SOURCE=.\example.h

+# End Source File

+# End Group

+# Begin Group "Resource Files"

+

+# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"

+# End Group

+# Begin Source File

+

+SOURCE=.\example.i

+

+!IF  "$(CFG)" == "example - Win32 Debug"

+

+# Begin Custom Build

+InputPath=.\example.i

+InputName=example

+

+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"

+	echo In order to function correctly, please ensure the following environment variables are correctly set: 

+	echo PYTHON_INCLUDE: %PYTHON_INCLUDE% 

+	echo PYTHON_LIB: %PYTHON_LIB% 

+	echo on 

+	..\..\..\swig.exe -c++ -python "$(InputPath)" 

+	

+# End Custom Build

+

+!ELSEIF  "$(CFG)" == "example - Win32 Release"

+

+# Begin Custom Build

+InputPath=.\example.i

+InputName=example

+

+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"

+	echo In order to function correctly, please ensure the following environment variables are correctly set: 

+	echo PYTHON_INCLUDE: %PYTHON_INCLUDE% 

+	echo PYTHON_LIB: %PYTHON_LIB% 

+	echo on 

+	..\..\..\swig.exe -c++ -python "$(InputPath)" 

+	

+# End Custom Build

+

+!ENDIF 

+

+# End Source File

+# End Target

+# End Project

diff --git a/Examples/python/doxygen/example.h b/Examples/python/doxygen/example.h
new file mode 100644
index 000000000..203348ae4
--- /dev/null
+++ b/Examples/python/doxygen/example.h
@@ -0,0 +1,107 @@
+/*! \file example.h 
+This file provides a simple set of Shape classes. */
+
+/*! Base class for all shapes.
+ \author Bob
+ */
+class Shape {
+public:
+  /*! Default constructor for creating a Shape */
+  Shape() {
+    nshapes++;
+  }
+  /*! Destructor for destroying a Shape */
+  virtual ~Shape() {
+    nshapes--;
+  }
+  double x; /*!< x co-ordinate */
+  double y; /*!< y co-ordinate */
+  void    move(double dx, double dy); /*!< Move a shape to a new co-ordinate
+  \param dx x co-ordinate
+  \param dy y co-ordinate */
+  virtual double area() = 0; /*!< \return the area */
+  virtual double perimeter() = 0; /*!< \return the perimeter */
+  static  int nshapes; /*!< Number of shapes currently in existence */
+};
+
+/*! A class for representing a circle.
+ \author Jack
+ */
+class Circle : public Shape {
+private:
+  double radius;
+public:
+  /*! Construct a circle
+   *  \param r radius of the circle */
+  Circle(double r);
+  /*! Calculate the area of the circle
+   *  \return calculated area */
+  virtual double area();
+  /*! Calculate the perimeter of the circle
+   *  \return calculated perimeter of the circle */
+  virtual double perimeter();
+};
+
+/// A class for representing a square.
+class Square : public Shape {
+private:
+  double width;
+public:
+  /** Construct a square
+   *  \param w width of the square */
+  Square(double w);
+  /** Calculate the area of the square
+   *  \return calculated area */
+  virtual double area();
+  /** Calculate the perimeter of the square
+   *  \return calculated perimeter of the square */
+  virtual double perimeter();
+};
+
+/// A class for representing a rectangle, templated on the type for the rectangle dimensions
+template<typename T>
+class Rectangle : public Shape {
+private:
+  T height;
+  T width;
+public:
+  /** Construct a rectangle
+   *  \param h height of the rectangle
+   *  \param w width of the rectangle */
+  Rectangle(T h, T w) : height(h), width(w) {}
+  /** Calculate the area of the rectangle
+   *  \return calculated area */
+  virtual double area() { return width*height; }
+  /** Calculate the perimeter of the rectangle
+   *  \return calculated perimeter of the rectangle */
+  virtual double perimeter() { return 2*height + 2*width; }
+};
+
+
+/*! Factory function for creating a square
+ *  \param r width of the square
+ *  \return a fully constructed square */
+Square MakeSquare(double r);
+
+/*! Factory function for creating a circle
+ *  \param w radius of the circle
+ *  \return a fully constructed circle */
+Circle MakeCircle(double w);
+
+/*! Factory function for creating a rectangle
+ *  \param h height of the rectangle
+ *  \param w width of the rectangle
+ *  \return a fully constructed rectangle */
+template<typename T>
+Rectangle<T> MakeRectangle(T h, T w) {
+  return Rectangle<T>(h, w);
+}
+
+
+
+/*! Total number of circles ever created */
+extern int NumCircles;
+
+/// Total number of squares ever created
+extern int NumSquares;
+
diff --git a/Examples/python/doxygen/example.i b/Examples/python/doxygen/example.i
new file mode 100644
index 000000000..803563dd9
--- /dev/null
+++ b/Examples/python/doxygen/example.i
@@ -0,0 +1,17 @@
+%module example
+
+%{
+#include "example.h"
+%}
+
+%immutable NumSquares;
+%immutable NumCircles;
+
+%include "example.h"
+
+/*! - this instantiation uses type int */
+%template(RectangleInt) Rectangle<int>;
+
+/*! - this instantiation uses type int */
+%template(MakeRectangleInt) MakeRectangle<int>;
+
diff --git a/Examples/python/doxygen/runme.py b/Examples/python/doxygen/runme.py
new file mode 100644
index 000000000..e23528874
--- /dev/null
+++ b/Examples/python/doxygen/runme.py
@@ -0,0 +1,28 @@
+# This example shows simple usage of the wrapped Shape classes.
+# The main purpose of this example is to show the doxygen comments translation to PyDoc comments.
+# Users should look at the generated example.py file.
+# The generated PyDoc can be viewed in a browser by opening the example.html file.
+
+import example
+
+print "Creating some objects:"
+c = example.MakeCircle(10)
+print "    Created circle", c
+s = example.MakeSquare(10)
+print "    Created square", s
+r = example.MakeRectangleInt(10, 20)
+print "    Created rectangle", r
+
+print "\nHere are some properties of the shapes:"
+for o in [c, s, r]:
+    print "   ", o
+    print "        area      = ", o.area()
+    print "        perimeter = ", o.perimeter()
+
+print "\nRunning pydoc, this is the equivalent to executing: pydoc -w ./example.py"
+
+import pydoc
+
+pydoc.writedoc("example")
+
+print "Open example.html in your browser to view the generated python docs"