Merge pull request numpy#21836 from NamamiShanker/doc_change

DOC: F2PY documentation improvements

doc/source/f2py/advanced.rst

@@ -96,6 +96,32 @@ and the corresponding <C type>. The <C type> can be one of the following::
     complex_long_double
     string
 
+For example, for a Fortran file ``func1.f`` containing:
+
+.. literalinclude:: ./code/f2cmap_demo.f
+    :language: fortran
+
+In order to convert ``int64`` and ``real64`` to valid ``C`` data types,
+a ``.f2py_f2cmap`` file with the following content can be created in the current directory:
+
+.. code-block:: python
+
+  dict(real=dict(real64='double'), integer=dict(int64='long long'))
+
+and create the module as usual. F2PY checks if a ``.f2py_f2cmap`` file is present
+in the current directory and will use it to map ``KIND`` specifiers to ``C`` data types.
+
+.. code-block:: sh
+
+  f2py -c func1.f -m func1
+
+Alternatively, the mapping file can be saved with any other name, for example 
+``mapfile.txt``, and this information can be passed to F2PY by using the ``--f2cmap`` option.
+
+.. code-block:: sh
+
+  f2py -c func1.f -m func1 --f2cmap mapfile.txt
+
 For more information, see F2Py source code ``numpy/f2py/capi_maps.py``.
 
 .. _Character strings:

doc/source/f2py/code/f2cmap_demo.f

@@ -0,0 +1,9 @@
+      subroutine func1(n, x, res)
+        use, intrinsic :: iso_fortran_env, only: int64, real64
+        implicit none
+        integer(int64), intent(in) :: n
+        real(real64), intent(in) :: x(n)
+        real(real64), intent(out) :: res
+Cf2py   intent(hide) :: n
+        res = sum(x)
+      end

doc/source/f2py/code/meson.build

@@ -20,19 +20,12 @@ incdir_f2py = run_command(py3,
     check : true
 ).stdout().strip()
 
-fibby_source = custom_target('fibbymodule.c',
-                            input : ['fib1.f'], # .f so no F90 wrappers
-                            output : ['fibbymodule.c', 'fibby-f2pywrappers.f'],
-                            command : [ py3, '-m', 'numpy.f2py', '@INPUT@',
-                            '-m', 'fibby', '--lower']
-                            )
-
 inc_np = include_directories(incdir_numpy, incdir_f2py)
 
-py3.extension_module('fibby',
+py3.extension_module('fib2',
            'fib1.f',
-           fibby_source,
+           'fib2module.c',
            incdir_f2py+'/fortranobject.c',
            include_directories: inc_np,
            dependencies : py3_dep,
-           install : true)
+           install : true)

doc/source/f2py/usage.rst

@@ -220,6 +220,8 @@ Other options
   ``--build-dir <dirname>``
     All F2PY generated files are created in ``<dirname>``. Default is
     ``tempfile.mkdtemp()``.
+  ``--f2cmap <filename>``
+    Load Fortran-to-C ``KIND`` specifications from the given file.
   ``--quiet``
     Run quietly.
   ``--verbose``