trunk: Fix PYDOC bug (add missing define), move instructions in the d…

…ocumentation from Installation to SCons; OS-unspecific details should only be mentioned on the Linux page to avoid redundancies. [base, pysgpp] git-svn-id: https://ipvs.informatik.uni-stuttgart.de/SGpp/repos/trunk@5342 4eea3252-f0fb-4393-894d-40516dce545b
SGpp · Dec 14, 2015 · 27bfcb1 · 27bfcb1
1 parent fea830f
commit 27bfcb1
Show file tree

Hide file tree

Showing 4 changed files with 26 additions and 21 deletions.
diff --git a/base/doc/doxygen/linux.doxy b/base/doc/doxygen/linux.doxy
@@ -46,7 +46,8 @@ The following software is recommended for core functionality:
   if you want to compile the Java bindings.
 - <a href="http://www.doxygen.org/" target="_blank">Doxygen</a> is required to
   create and compile the documentation, which you are reading right now.
-  It is also required to build the python documentation.
+  It is also required to automatically annotate the Python bindings
+  generated by SWIG with docstrings.
 
 @subsection linux_dependencies_optional Optional
 
@@ -137,10 +138,6 @@ Also, there are two switches for supported high-level back-ends:
 - <tt>SG_PYTHON</tt>: Python bindings
 - <tt>SG_JAVA</tt>: Java bindings
 
-There is a inline documentation of the python wrapper which can be disabled
-by setting <tt>PYDOC=0</tt>. It is recommended to disable this feature if
-you are developing and have to frequently recompile the whole codebase.
-
 For example, the command
 @verbatim
 scons SG_OPTIMIZATION=0
@@ -161,6 +158,11 @@ By default, the Python bindings are built, too.
 If not, then some prerequisites are missing
 (see \ref linux_dependencies).
 
+By default, the Python bindings will be annotated with Python docstrings,
+if Doxygen is installed.
+Disabling this feature, which is recommended if you have to recompile the whole codebase frequently, is done by setting <tt>PYDOC=0</tt> in the
+SCons command line.
+
 When the build is finished,
 the Python bindings are installed in <tt>lib/pysgpp</tt>.
 If you use them, add the <tt>lib</tt> directory to your <tt>PYTHONPATH</tt>.

diff --git a/base/doc/doxygen/mingw.doxy b/base/doc/doxygen/mingw.doxy
@@ -64,7 +64,8 @@ The following software is recommended for core functionality:
   if you want to compile the Java bindings.
 - <a href="http://www.doxygen.org/" target="_blank">Doxygen</a> is required to
   create and compile the documentation, which you are reading right now.
-  It is also required to build the python documentation.
+  It is also required to automatically annotate the Python bindings
+  generated by SWIG with docstrings.
 
 @subsection mingw_dependencies_optional Optional
 
@@ -143,10 +144,6 @@ b2 --with-test ^
    2. Extract the archive.
    3. Prepend <tt>C:\\PATH_TO_SWIG</tt> to the <tt>PATH</tt>
       environment variable.
-   4. If you want there is a inline documentation of the python wrapper which can be disabled
-      by setting <tt>PYDOC=0</tt>. It is recommended to disable this feature if
-      you are developing and have to frequently recompile the whole codebase.
-
 7. NumPy:
    1. Download <tt>numpy‑1.9.3+mkl‑cp27‑none‑win_amd64.whl</tt> or similar
       from <a href="http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy"

diff --git a/base/doc/doxygen/msvc.doxy b/base/doc/doxygen/msvc.doxy
@@ -76,7 +76,8 @@ and use the Python and Java/MATLAB interface.
   if you want to compile the Java bindings.
 - <a href="http://www.doxygen.org/" target="_blank">Doxygen</a> is required to
   create and compile the documentation, which you are reading right now.
-  It is also required to build the python documentation.
+  It is also required to automatically annotate the Python bindings
+  generated by SWIG with docstrings.
 
 @subsection msvc_dependencies_optional Optional
 
@@ -97,10 +98,7 @@ and use the Python and Java/MATLAB interface.
    the path to the libraries needs to be added to @c PATH.
 5. Interfaces to Python and Java:
    1. Install SWIG and add it to @c PATH.
-   2. Python: You need to install NumPy. There is a inline documentation of the python wrapper which can be disabled
-      by setting <tt>PYDOC=0</tt>. It is recommended to disable this feature if
-      you are developing and have to frequently recompile the whole codebase.
-
+   2. Python: You need to install NumPy.
    3. Java: Install JDK and JRE for Java support.
       Please check the platform (x86 or x64).
       Add javac.exe (you can find it in the installation of the JDK) to @c PATH.

diff --git a/pysgpp/SConscript b/pysgpp/SConscript
@@ -28,15 +28,23 @@ elif env['PLATFORM'] == 'darwin':
     py_env['SHLIBSUFFIX'] = '.so'
 
 # build python module with swig
-swigflags = ['-c++', '-python', '-fvirtual'] + ['-D' + c for c in py_env['CPPDEFINES']]
+swigflags = ['-c++', '-python', '-fvirtual']
+swigflags.extend(['-D' + c for c in py_env['CPPDEFINES']])
+
+# tell SWIG that we're on Windows
+# (SCons/SWIG do not seem to set this flag automatically)
 if env['COMPILER'] == 'vcc':
-    # scons/swig does not seem to set this flag automatically
     swigflags.append('-DSWIGWIN')
 
-py_env.AppendUnique(SWIGFLAGS=swigflags)
+# Python docstrings in SWIG-generated Python file
+if env['PYDOC']:
+    swigflags.append('-DPYDOC')
 
+# set single precision define
 if not py_env['USE_DOUBLE_PRECISION']:
-    py_env.AppendUnique(SWIGFLAGS=['-DUSE_DOUBLE_PRECISION=0'])
+    swigflags.append('-DUSE_DOUBLE_PRECISION=0')
+
+py_env.AppendUnique(SWIGFLAGS=swigflags)
 
 pythonLibPaths = [BUILD_DIR]
 if env['PLATFORM'] == 'win32':
@@ -104,8 +112,8 @@ def setupPython(target, source, env):
     fd.close()
 
 if env['PYDOC']:
-   Import('pydocTargetList')
-   py_env.Depends(libPython, pydocTargetList)
+    Import('pydocTargetList')
+    py_env.Depends(libPython, pydocTargetList)
 
 installLibPython = py_env.Install(PYSGPP_BUILD_PATH, libPython)
 installLibWrapperPython = py_env.Install(PYSGPP_BUILD_PATH, "pysgpp_swig.py")