DOC: Address build system review I

Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>
Co-authored-by: Christoph Buchner <bilderbuchi@phononoia.at>
Co-authored-by: Melissa Weber Mendonça <melissawm@gmail.com>

5 files changed, 34 insertions, 18 deletions

diff --git a/doc/source/f2py/buildtools/cmake.rst b/doc/source/f2py/buildtools/cmake.rst
index f7c69a8bb..3ed5a2bee 100644
--- a/doc/source/f2py/buildtools/cmake.rst
+++ b/doc/source/f2py/buildtools/cmake.rst
@@ -10,7 +10,7 @@ learning curve is steeper since CMake syntax is not pythonic and is closer to
 
 However, the trade-off is enhanced flexibility and support for most architectures
 and compilers. An introduction to the syntax is out of scope for this document,
-but the `official CMake Tutorials`_ are a fantastic resource.
+but this `extensive CMake collection`_ of resources is great.
 
 .. note::
 
@@ -57,4 +57,4 @@ with the ``cython`` information.
 This is particularly useful where an existing toolchain already exists and
 ``scikit-build`` or other additional ``python`` dependencies are discouraged.
 
-.. _official CMake Tutorials: https://cmake.org/cmake/help/latest/guide/tutorial/index.html
+.. _extensive CMake collection: https://cliutils.gitlab.io/modern-cmake/
diff --git a/doc/source/f2py/buildtools/index.rst b/doc/source/f2py/buildtools/index.rst
index 959301ec5..aa41fd37f 100644
--- a/doc/source/f2py/buildtools/index.rst
+++ b/doc/source/f2py/buildtools/index.rst
@@ -53,7 +53,7 @@ Fortran 77 programs
    arrays.
 
 Fortran 90 programs
-   - Input file ``blah.f``
+   - Input file ``blah.f90``
    - Generates:
 
      + ``blahmodule.c``
@@ -75,6 +75,10 @@ Signature files
    their contents; which shifts the burden of checking for generated files onto
    the build system.
 
+.. note::
+
+   The signature file output situation is being reconsidered in `issue 20385`_ .
+
 
 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
@@ -94,3 +98,5 @@ Build Systems
    meson
    cmake
    skbuild
+
+.. _`issue 20385`: https://github.com/numpy/numpy/issues/20385
diff --git a/doc/source/f2py/buildtools/meson.rst b/doc/source/f2py/buildtools/meson.rst
index d18715bbf..d98752e65 100644
--- a/doc/source/f2py/buildtools/meson.rst
+++ b/doc/source/f2py/buildtools/meson.rst
@@ -31,12 +31,6 @@ examples from :ref:`f2py-getting-started` section:
 .. literalinclude:: ./../code/meson.build
     :language: meson
 
-.. note::
-
-    * The ``fortranobject.{c,h}`` files have to be included in the manner shown,
-      by referencing the ``.c`` file and adding to the include directories.
-    * The warning level is lower than that of a build set up with ``meson init``
-
 At this point the build will complete, but the import will fail:
 
 .. code-block:: bash
diff --git a/doc/source/f2py/buildtools/skbuild.rst b/doc/source/f2py/buildtools/skbuild.rst
index 59fe2f822..af18ea43b 100644
--- a/doc/source/f2py/buildtools/skbuild.rst
+++ b/doc/source/f2py/buildtools/skbuild.rst
@@ -5,7 +5,8 @@ Using via ``scikit-build``
 ============================
 
 ``scikit-build`` provides two separate concepts geared towards the users of Python extension modules.
-1. A ``setuptools`` replacement
+
+1. A ``setuptools`` replacement (legacy behaviour)
 2. A series of ``cmake`` modules with definitions which help building Python extensions
 
 .. note::
@@ -53,6 +54,13 @@ The resulting extension can be built and loaded in the standard workflow.
 ``setuptools`` replacement
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. note::
+
+   **As of November 2021**
+
+   The behavior described here of driving the ``cmake`` build of a module is
+   considered to be legacy behaviour and should not be depended on.
+
 The utility of ``scikit-build`` lies in being able to drive the generation of
 more than extension modules, in particular a common usage pattern is the
 generation of Python distributables (for example for PyPI).
@@ -62,13 +70,15 @@ The workflow with ``scikit-build`` straightforwardly supports such packaging req
 .. literalinclude:: ./../code/setup_skbuild.py
    :language: python
 
-Along with a commiserate ``pyproject.toml``
+Along with a commensurate ``pyproject.toml``
 
 .. literalinclude:: ./../code/pyproj_skbuild.toml
    :language: toml
 
 Together these can build the extension using ``cmake`` in tandem with other
-standard ``setuptools`` outputs.
+standard ``setuptools`` outputs. Running ``cmake`` through ``setup.py`` is
+mostly used when it is necessary to integrate with extension modules not built
+with ``cmake``.
 
 .. code:: bash
 
diff --git a/doc/source/f2py/code/CMakeLists.txt b/doc/source/f2py/code/CMakeLists.txt
index 90f8fbac1..62ff193bb 100644
--- a/doc/source/f2py/code/CMakeLists.txt
+++ b/doc/source/f2py/code/CMakeLists.txt
@@ -1,5 +1,5 @@
 ### setup project ###
-cmake_minimum_required(VERSION 3.17.3)
+cmake_minimum_required(VERSION 3.17.3) # 3.17 > for Python3_SOABI
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 project(fibby
@@ -41,15 +41,21 @@ message(STATUS ${Python3_INCLUDE_DIRS})
 message(STATUS ${F2PY_INCLUDE_DIR})
 message(STATUS ${Python3_NumPy_INCLUDE_DIRS})
 
+# Vars
+set(f2py_module_name "fibby")
+set(fortran_src_file "${CMAKE_SOURCE_DIR}/fib1.f")
+set(f2py_module_c "${f2py_module_name}module.c")
+set(generated_module_file "${f2py_module_name}${Python3_SOABI}")
+
 # Generate sources
 add_custom_target(
   genpyf
-  DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}module.c"
+  DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${f2py_module_c}"
   )
 add_custom_command(
-  OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}module.c"
+  OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${f2py_module_c}"
   COMMAND ${Python3_EXECUTABLE}  -m "numpy.f2py"
-                   "${CMAKE_SOURCE_DIR}/fib1.f"
+                   "${fortran_src_file}"
                    -m "fibby"
                    --lower # Important
   DEPENDS fib1.f # Fortran source
@@ -57,9 +63,9 @@ add_custom_command(
 
 # Set up target
 add_library(${CMAKE_PROJECT_NAME} SHARED
-  "${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}module.c" # Generated
+  "${CMAKE_CURRENT_BINARY_DIR}/${f2py_module_c}" # Generated
   "${F2PY_INCLUDE_DIR}/fortranobject.c" # From NumPy
-  fib1.f # Fortran source(s)
+  "${fortran_src_file}" # Fortran source(s)
   )
 
 # Depend on sources