docs/userguide/ext_modules.rst: New

[mkoeppe]

Summary of changes

Add documentation on build_ext as requested by @jaraco in python/cpython#90539 (comment)

Pull Request Checklist

• Changes have tests
• News fragment added in changelog.d/.
  (See documentation for details)

[abravalheri]

Thank you very much @mkoeppe!

This is indeed a part of setuptools that is under documented and that sometimes requires users to read the distutils docs, which may be outdated and confusing.

I plan to add some example and a few remarks to the PR... I hope you don't mind.

[abravalheri]

I added some changes in the spirit of improving the docs:

• I tried to provide a very simple example, just to show to the beginners how they can start adding extensions
• I added a few remarks and some links to other useful tools that can be used together with setuptools.
• I also did some editorial/cosmetic changes (and tried to make sphinx more satisfied in terms of warnings).
• I added proper docstrings to setuptools.Extension (mostly copied from distutils.extension.Extension). We can argue that there is a lot of duplication between the docstrings of these 2 classes, but I could not find a way of making sphinx reuse the docstring while tweaking part of its contents (so I guess that is the best we can do).
• For the time being I am placing the API description for setuptools.Extension in this document, because setuptools does not document the parts of its API that are public. In the future we can move the autodocs to a better place (but I think we can provisionally leave it there).

You can see the final result in https://setuptools--3368.org.readthedocs.build/en/3368/userguide/ext_modules.html.

I hope you don't mind the updates...

Please let me know if you would like to change anything, otherwise I plan to merge the PR very soon.

[abravalheri]

@Mergifyio rebase

[mergify]

rebase

✅ Branch has been successfully rebased

[mkoeppe]

I added some changes in the spirit of improving the docs

Thanks very much, looking great.