doc: document public API clearly (#3917)

Author: ilan-gold

README.md

@@ -39,6 +39,19 @@ If you like scverse® and want to support our mission, please consider making a
 </a>
 </div>
 
+## Public API
+
+Our public API is documented in the [API section][] of these docs.
+We cannot guarantee the stability of our internal APIs, whether it's the location of a function, its arguments, or something else.
+In other words, we do not officially support (or encourage users to do) something like `from scanpy.logging import debug` as `logging` is not documented, even though it does not contain a [leading underscore][].
+However, we are aware that many users do use these internal APIs and thus encourage them to [open an issue][] or migrate to the public API.
+That is, if something is missing from our public API as documented, for example a feature you wish to be exported publicly, please open an issue.
+
+[api section]: https://scanpy.readthedocs.io/en/stable/api.html
+[leading underscore]: https://peps.python.org/pep-0008/#public-and-internal-interfaces
+[open an issue]: https://github.com/scverse/scanpy/issues/new/choose
+
+
 
 ## Citation