Merge branch 'mromberg-extend'

* mromberg-extend:
  Python docs on static linking section edits
  Add more documentation about statically linked python modules.

Doc/Manual/Contents.html

@@ -1600,6 +1600,7 @@ <h3><a href="Python.html#Python">36 SWIG and Python</a></h3>
 <li><a href="Python.html#Python_package_search_both_package_modules">Both modules in the same package</a>
 <li><a href="Python.html#Python_package_search_wrapper_split">Split modules</a>
 <li><a href="Python.html#Python_package_search_both_global_modules">Both modules are global</a>
+<li><a href="Python.html#Python_package_search_static">Statically linked C modules</a>
 </ul>
 </ul>
 <li><a href="Python.html#Python_python3support">Python 3 Support</a>

Doc/Manual/Python.html

@@ -122,6 +122,7 @@ <H1><a name="Python">36 SWIG and Python</a></H1>
 <li><a href="#Python_package_search_both_package_modules">Both modules in the same package</a>
 <li><a href="#Python_package_search_wrapper_split">Split modules</a>
 <li><a href="#Python_package_search_both_global_modules">Both modules are global</a>
+<li><a href="#Python_package_search_static">Statically linked C modules</a>
 </ul>
 </ul>
 <li><a href="#Python_python3support">Python 3 Support</a>
@@ -6065,6 +6066,78 @@ <H4><a name="Python_package_search_both_global_modules">36.11.6.3 Both modules a
 as desired.
 </p>
 
+<H4><a name="Python_package_search_static">36.11.6.4 Statically linked C modules</a></H4>
+
+
+<p>It is strongly recommended to use dynamically linked modules for the C
+portion of your pair of Python modules.
+If for some reason you still need
+to link the C module of the pair of Python modules generated by SWIG into
+your interpreter, then this section provides some details on how this impacts
+the pure Python modules ability to locate the other part of the pair.
+Please also see the <a href="Python.html#Python_nn8">Static Linking</a> section.
+</p>
+
+<p>When Python is extended with C code the Python interpreter needs to be
+informed about details of the new C functions that have been linked into
+the executable.  The code to do this is created by SWIG and is automatically
+called in the correct way when the module is dynamically loaded.  However
+when the code is not dynamically loaded (because it is statically linked)
+Then the initialization method for the module created by SWIG is not
+called automatically and the Python interpreter has no idea that the
+new SWIG C module exists.
+</p>
+
+<p>Before Python 3, one could simply call the init method created by SWIG
+which would have normally been called when the shared object was dynamically
+loaded.  The specific name of this method is not given here because statically
+linked modules are not encouraged with SWIG
+(<a href="Python.html#Python_nn8">Static Linking</a>).  However one can find this
+init function in the C file generated by SWIG.
+</p>
+
+<p>If you are really keen on static linking there are two ways
+to initialize the SWIG generated C module with the init method.  Which way
+you use depends on what version of Python your module is being linked with.
+Python 2 and Python 3 treat this init function differently.  And the way
+they treat it affects how the pure Python module will be able to
+locate the C module.
+</p>
+
+<p>The details concerning this are covered completly in the documentation
+for Python itself.  Links to the relavent sections follow:
+</p>
+
+<ul>
+  <li><a href="https://docs.python.org/2/extending/extending.html#methodtable">Extending in python2</a></li>
+  <li><a href="https://docs.python.org/3.6/extending/extending.html#the-module-s-method-table-and-initialization-function">Extending in python3</a></li>
+</ul>
+
+<p>There are two keys things to understand.  The first is that in
+Python 2 the init() function returns void.  In Python 3 the init() function
+returns a PyObject * which points to the new module.  Secondly, when
+you call the init() method manually, you are the Python importer.  So, you
+determine which package the C module will be located in.
+</p>
+
+<p>So, if you are using Python 3 it is important that you follow what is
+described in the Python documentation linked above.  In particular, you can't
+simply call the init() function generated by SWIG and cast the PyObject
+pointer it returns over the side.  If you do then Python 3 will have no
+idea that your C module exists and the pure Python half of your wrapper will
+not be able to find it.  You need to register your module with the Python
+interpreter as described in the Python docs.
+</p>
+
+<p>With Python 2 things are somewhat more simple.  In this case the init function
+returns void.  Calling it will register your new C module as a <b>global</b>
+module.  The pure Python part of the SWIG wrapper will be able to find it
+because it tries both the pure Python module it is part of and the global
+module.  If you wish not to have the statically linked module be a global
+module then you will either need to refer to the Python documentation on how
+to do this (remember you are now the Python importer) or use dynamic linking.
+</p>
+
 <H2><a name="Python_python3support">36.12 Python 3 Support</a></H2>