sagemathgh-36557: src/doc/en/developer: Describe static typing workflow

    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes sagemath#1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->
We add a section in the developer's guide to explain how to add typing
annotations.

<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes sagemath#12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [ ] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- sagemath#12345: short description why this is a dependency
- sagemath#34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: sagemath#36557
Reported by: Matthias Köppe
Reviewer(s): Eric Gourgoulhon, Matthias Köppe, Tobias Diez

src/doc/en/developer/coding_in_python.rst

@@ -585,6 +585,57 @@ by
         return initialize_big_data()
 
 
+Static typing
+=============
+
+Python libraries are increasingly annotated with static typing information;
+see the `Python reference on typing <https://docs.python.org/3/library/typing.html>`_.
+
+For typechecking the Sage library, the project uses :ref:`pyright <section-tools-pyright>`;
+it automatically runs in the GitHub Actions CI and can also be run locally.
+
+As of Sage 10.2, the Sage library only contains a minimal set of such type
+annotations. Pull requests that add more annotations are generally welcome.
+
+The Sage library makes very extensive use of Cython (see chapter :ref:`chapter-cython`).
+Although Cython source code often declares static types for the purpose of
+compilation to efficient machine code, this typing information is unfortunately
+not visible to static checkers such as Pyright. It is necessary to create `type stub
+files (".pyi") <https://github.com/microsoft/pyright/blob/main/docs/type-stubs.md>`_
+that provide this information. Although various
+`tools for writing and maintaining type stub files
+<https://typing.readthedocs.io/en/latest/source/writing_stubs.html#writing-and-maintaining-stub-files>`_
+are available, creating stub files for Cython files involves manual work.
+There is hope that better tools become available soon, see for example
+`cython/cython #5744 <https://github.com/cython/cython/pull/5744>`_.
+Contributing to the development and testing of such tools likely will have a
+greater impact than writing the typestub files manually.
+
+For Cython modules of the Sage library, these type stub files would be placed
+next to the ``.pyx`` and ``.pxd`` files.
+
+When importing from other Python libraries that do not provide sufficient typing
+information, it is possible to augment the library's typing information for
+the purposes of typechecking the Sage library:
+
+- Create typestub files and place them in the directory ``SAGE_ROOT/src/typings``.
+  For example, the distribution **pplpy** provides the top-level package :mod:`ppl`,
+  which publishes no typing information. We can create a typestub file
+  ``SAGE_ROOT/src/typings/ppl.pyi`` or ``SAGE_ROOT/src/typings/ppl/__init__.pyi``.
+
+- When these typestub files are working well, it is preferable from the viewpoint
+  of the Sage project that they are "upstreamed", i.e., contributed to the
+  project that maintains the library. If a new version of the upstream library
+  becomes available that provides the necessary typing information, we can
+  update the package in the Sage distribution and remove the typestub files again
+  from ``SAGE_ROOT/src/typings``.
+
+- As a fallback, when neither adding typing annotations to source files
+  nor adding typestub files is welcomed by the upstream project, it is possible
+  to `contribute typestubs files instead to the typeshed community project
+  <https://github.com/python/typeshed/blob/main/CONTRIBUTING.md>`_.
+
+
 Deprecation
 ===========