DOC: Reword f2py docs

Author: HaoZeke

doc/source/f2py/advanced.rst

@@ -1,11 +1,11 @@
-======================
-Advanced F2PY usages
-======================
+========================
+Advanced F2PY use cases
+========================
 
-Adding self-written functions to F2PY generated modules
-=======================================================
+Adding user-defined functions to F2PY generated modules
+=========================================================
 
-Self-written Python C/API functions can be defined inside
+User-defined Python C/API functions can be defined inside
 signature files using ``usercode`` and ``pymethoddef`` statements
 (they must be used inside the ``python module`` block). For
 example, the following signature file ``spam.pyf``
@@ -17,32 +17,30 @@ wraps the C library function ``system()``::
 
   f2py -c spam.pyf
 
-In Python:
+In Python this can then be used as:
 
-.. include:: ./code/results/spam_session.dat
-   :literal:
-
-Modifying the dictionary of a F2PY generated module
-===================================================
+.. literalinclude:: ./code/results/spam_session.dat
+   :language: python
 
-The following example illustrates how to add user-defined
-variables to a F2PY generated extension module. Given the following
-signature file
+Adding user-defined variables
+==============================
 
-.. include:: ./code/var.pyf
-  :literal:
+The following example illustrates how to add user-defined variables to a F2PY
+generated extension module by modifying the dictionary of a F2PY generated
+module. Consider the following signature file (compiled with ``f2py -c var.pyf``):
 
-compile it as ``f2py -c var.pyf``.
+.. literalinclude:: ./code/var.pyf
+  :language: fortran
 
 Notice that the second ``usercode`` statement must be defined inside
-an ``interface`` block and where the module dictionary is available through
-the variable ``d`` (see ``f2py var.pyf``-generated ``varmodule.c`` for
+an ``interface`` block and the module dictionary is available through
+the variable ``d`` (see ``varmodule.c`` generated by ``f2py var.pyf`` for
 additional details).
 
-In Python:
+Usage in Python:
 
-.. include:: ./code/results/var_session.dat
-  :literal:
+.. literalinclude:: ./code/results/var_session.dat
+  :language: python
 
 
 Dealing with KIND specifiers
@@ -70,7 +68,7 @@ Use the ``--f2cmap`` command-line option to pass the file name to F2PY.
 By default, F2PY assumes file name is ``.f2py_f2cmap`` in the current
 working directory.
 
-Or more generally, the f2cmap file must contain a dictionary
+More generally, the f2cmap file must contain a dictionary
 with items::
 
     <Fortran typespec> : {<selector_expr>:<C type>}
@@ -79,7 +77,7 @@ that defines mapping between Fortran type::
 
     <Fortran typespec>([kind=]<selector_expr>)
 
-and the corresponding <C type>. <C type> can be one of the following::
+and the corresponding <C type>. The <C type> can be one of the following::
 
     char
     signed_char
@@ -94,4 +92,4 @@ and the corresponding <C type>. <C type> can be one of the following::
     complex_long_double
     string
 
-For more information, see F2Py source code ``numpy/f2py/capi_maps.py``.
+For more information, see the F2Py source code ``numpy/f2py/capi_maps.py``.

doc/source/f2py/distutils.rst

@@ -4,13 +4,14 @@ Using via `numpy.distutils`
 
 .. currentmodule:: numpy.distutils.core
 
-:mod:`numpy.distutils` is part of NumPy extending standard Python ``distutils``
-to deal with Fortran sources and F2PY signature files, e.g. compile Fortran
-sources, call F2PY to construct extension modules, etc.
+:mod:`numpy.distutils` is part of NumPy; and extends the standard Python
+``distutils`` module to deal with Fortran sources and F2PY signature files, e.g.
+compile Fortran sources, call F2PY to construct extension modules, etc.
 
 .. topic:: Example
 
-  Consider the following `setup file`__:
+  Consider the following `setup file`__ for the ``fib`` examples in the previous
+  section:
 
   .. literalinclude:: ./code/setup_example.py
     :language: python
@@ -26,30 +27,32 @@ sources, call F2PY to construct extension modules, etc.
 
   __ setup_example.py
 
+Extensions to ``distutils``
+===========================
+
 :mod:`numpy.distutils` extends ``distutils`` with the following features:
 
 * :class:`Extension` class argument ``sources`` may contain Fortran source
   files. In addition, the list ``sources`` may contain at most one
-  F2PY signature file, and then the name of an Extension module must
-  match with the ``<modulename>`` used in signature file.  It is
+  F2PY signature file; in this case, the name of an Extension module must
+  match with the ``<modulename>`` used in signature file. It is
   assumed that an F2PY signature file contains exactly one ``python
   module`` block.
 
-  If ``sources`` does not contain a signature files, then F2PY is used
-  to scan Fortran source files for routine signatures to construct the
-  wrappers to Fortran codes.
+  If ``sources`` do not contain a signature file, then F2PY is used to scan
+  Fortran source files to construct wrappers to the Fortran codes.
 
-  Additional options to F2PY process can be given using :class:`Extension`
-  class argument ``f2py_options``.
+  Additional options to the F2PY executable can be given using the
+  :class:`Extension` class argument ``f2py_options``.
 
 * The following new ``distutils`` commands are defined:
 
   ``build_src``
     to construct Fortran wrapper extension modules, among many other things.
   ``config_fc``
-    to change Fortran compiler options
+    to change Fortran compiler options.
 
-  as well as ``build_ext`` and  ``build_clib`` commands are enhanced
+  as well as ``build_ext`` and  ``build_clib`` commands which are also enhanced
   to support Fortran sources.
 
   Run
@@ -60,14 +63,14 @@ sources, call F2PY to construct extension modules, etc.
 
   to see available options for these commands.
 
-* When building Python packages containing Fortran sources, then one
-  can choose different Fortran compilers by using ``build_ext``
+* When building Python packages containing Fortran sources, one
+  can choose different Fortran compilers by using the ``build_ext``
   command option ``--fcompiler=<Vendor>``. Here ``<Vendor>`` can be one of the
   following names::
 
     absoft sun mips intel intelv intele intelev nag compaq compaqv gnu vast pg hpux
 
-  See ``numpy_distutils/fcompiler.py`` for up-to-date list of
+  See ``numpy_distutils/fcompiler.py`` for an up-to-date list of
   supported compilers or run
 
   ::