DOC: F2PY build system overview

1 files changed, 43 insertions, 1 deletions

diff --git a/doc/source/f2py/buildtools/index.rst b/doc/source/f2py/buildtools/index.rst
index dbc1aca0c..de8ea9212 100644
--- a/doc/source/f2py/buildtools/index.rst
+++ b/doc/source/f2py/buildtools/index.rst
@@ -2,7 +2,7 @@
 F2PY and Build Systems
 =======================
 
-In this chapter we will cover the various popular build systems and their usage
+In this section we will cover the various popular build systems and their usage
 with ``f2py``.
 
 .. note::
@@ -15,6 +15,48 @@ with ``f2py``.
    in the future. Alternative methods are thus increasingly more important.
 
 
+Basic Concepts
+===============
+
+Building an extension module which includes Python and Fortran consists of:
+
+- Fortran source(s)
+- One or more generated files from ``f2py``
+
+  + A ``C`` wrapper file is always created
+  + Code with modules require an additional ``.f90`` wrapper
+
+- ``fortranobject.{c,h}``
+
+  + Distributed with ``numpy``
+  + Can be queried via ``python -c "import numpy.f2py; print(numpy.f2py.get_include())"``
+
+- NumPy headers
+
+  + Can be queried via ``python -c "import numpy; print(numpy.get_include())"``
+
+- Python libraries and development headers
+
+Broadly speaking there are two cases which arise when considering the outputs of ``f2py``:
+
+Fortran 77 programs
+   - Input file ``blah.f``
+   - Generates ``blahmodule.c`` **default name**
+
+   In this instance, only a ``C`` wrapper file is generated and only one file needs to be kept track of.
+
+Fortran 90 programs
+   - Input file ``blah.f``
+   - Generates:
+     + ``blahmodule.c``
+     + ``blah-f2pywrappers2.f90``
+
+   The secondary wrapper is used to handle code which is subdivided into modules.
+
+In theory keeping the above requirements in hand, any build system can be
+adapted to generate ``f2py`` extension modules. Here we will cover a subset of
+the more popular systems.
+
 Build Systems
 ==============