[WIP] DOC: remove numpy.distutils references from f2py docs

[eagunn]

This is an installment in addressing ticket #25597, tackling only the f2py documentation.

This is a draft only. I will need some feedback on my edits before this change is ready for CI. @HaoZeke, when you have time could you review, using my list below to point out changes that may surprise or displease you.

[skip actions] [skip azp] [skip cirrus]

Context

This change is not as simple or local as I originally expected.

• In f2py/buildtools/index.rst, I pulled the distutils text near the top but then had a stab of conscience and added a brief note toward the bottom with a breadcrumb leading back to the last stable version that contained the distutils info. It seemed potentially disorienting to write as if distutils had never existed. But I'll be happy to pull the note if it is deemed unnecessary.
• I changed the note at the top of f2py/buildtools/meson.rst to make it more coherent (to me).
• I had to change two files outside of the f2py/buildtools folder in order to delete references to the now-deleted content.
• (Mea culpa in advance. Simply say if this is a change too far.) I converted an orphan bullet in f2py/f2py.getting-started.rst into a paragraph.

[eagunn]

When someone has time, possibly @HaoZeke or @rgommers, I could use some guidance on how to address the two pipeline failures. Both appear to be failing in an "install utilities" step. I'm not sure how my changes would drive such a failure.

[rgommers]

I'm not sure how my changes would drive such a failure.

Not sure since I have never seen this before. Your commit message may be related, it contains:

[skip ci] [skip actions] [skip azp] [skip cirrus]

all those are individually correct, but [skip ci] shouldn't be used here since it's a superset of the others. Maybe two skip commands confuse Azure.

If you want only the docs to build on CircleCI, use: [skip actions] [skip azp] [skip cirrus]

[eagunn]

@rgommers You nailed it in one. Thank you.

[eagunn]

In looking for additional references to distutils, I find that I missed:

• several mentions in doc/source/f2py/usage.rst
• one in doc/source/f2py/windows/index.rst

It would seem to make sense for those files to be cleaned up in this PR.

Unfortunately, I'm traveling most days from now till 13 June. If I get feedback from @HaoZeke on the changes listed in my Context section above, I'll get back to work on this in mid-June and do my best to incorporate these missed files. If, instead, getting distutils references cleaned up becomes a priority for someone else, I'd be happy to have them incorporate some or all of my changes into another PR and this one be closed/abandoned.

[HaoZeke]

I think we should have a link here to the document in question. Also, possibly in scope for this PR is that we still have distutils as the default if the Python version is less than 3.12 (see f2py2e.py around 556).

[HaoZeke]

In fact, perhaps until 3.12 becomes the lowest supported version we should keep distutils-to-meson.rst since (most) F2PY users probably haven't transitioned.

[HaoZeke]

Hi @eagunn, I took a quick look, and raised some discussion points, other than that the changes look good, hope travel is going well!

[mattip]

@eagunn is this still active?

[eagunn]

@mattip, Thanks for asking. I haven't abandoned it. However, while I was waiting for input I decided to tackle a less complicated set of changes so I could get through the commit/PR/merge cycle a couple of times. (And, I just had my very first PR merged. Huzzah!)

I hope to get back to this PR next week, take on board the comments above, and then simplify/finalize it.

[eagunn]

I'm closing this PR. It was a poor choice for a first-issue for me to work on. There are some issues of technical substance and of timing that I still do not understand. I'm preserving the branch in my own repo and @HaoZeke's helpful comments in case I want to work on it again later. For now, though, it is cruft in this repo that we don't need to have lying around.