Document high-level API concepts in an easier format

I have been thinking about this a fair bit, sparked by recently spending way too many hours to get some documentation to display correctly on api.drupal.org. Once that task was done, the next thing I did was look at what Symfony does. The reStructuredText (RST) format certainly looks much better for writing example code than what we have now. As for prose, I don't think there is as much of a difference, but still RST is easier. I did note that in the Symfony docs one can't view a single php file.

For the proposals

1. Doing this is more likely to lead to improvements than the longer path of creating an issue, MR, and so.

2. What I think about here are, in no order, a) how the docs will be structured, b) need to follow a page of instructions to get setup to contribute, c) who has commit access, d) may not improve the documentation, e) adds a new place to find documentation without removing one. But I do think this should be pursued. And proposal 1 can happen independently of the decision on this.

And with both 1 and 2 we don't have to wait 1 week for api.drupal.org to be re-parsed for the doc to be updated.

Agree with most of the proposed resolution. My thoughts:

1. Move long form texts to a new /docs folder in core (and contrib). The folder contains markdown files. Publish the docs via mkdocs or any other static site generator (SSG) that core prefers. mkdocs is the the SSG behind DDEVand Drush docs. We already support this in our Gitlab templates. Benefits:
   1. Once we are fully on Gitlab, it becomes super friendly to non devs and lazy devs to submit an MR via the Gitlab UI to change the docs.
   2. Docs can change along with code
   3. Docs automatically vary by branch.
2. Retire the api module and use Doctum or similar external project to generate our API docs. We can start with Drupal 12, and keep the API module docs as more or less static for older versions.