Merge pull request numpy#19893 from HaoZeke/f2py_docclean

MAINT,DOC: f2py restructring

Author: charris

doc/source/f2py/advanced.rst

@@ -1,48 +1,46 @@
-======================
-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``
 
-.. include:: spam.pyf
+.. include:: ./code/spam.pyf
    :literal:
 
 wraps the C library function ``system()``::
 
   f2py -c spam.pyf
 
-In Python:
+In Python this can then be used as:
 
-.. include:: 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:: 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:: 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``.