Update userguide on `miscellaneous` and `extension`

This is a continuation of the update effort to de-emphasize `distutils`
and make the documentation more consistent.

The main targets of the changes are the files
`docs/userguide/miscellaneous` and `docs/userguide/extension`.

Changes:

- Extracted text about automatic resource extraction and the zip-safe flag
  from `userguide/miscellaneous` to `deprecated/resource_extraction` and
  `deprecated/zip_safe`.
  - These configuration parameters are commonly associated with
    ``eggs``/``easy_install``/``pkg_resources``, and therefore are
    obsolete. Leaving them around in the main parts of the documentation
    just confuses users.
  - The text in the new files were updated.
- Extracted text about additional metadata from
  `userguide/miscellaneous` into the existing `userguide/extension`
  document.
- Updated `userguide/extension` to better reflect the status of the
  setuptools project.
  The text was also changed to explain a little bit more what is the
  relationship between ``setuptools`` and ``distutils``.
- Removed `userguide/functionalities_rewrite`.
  This file was virtually empty and not bringing any extra value to the
  docs.

1 files changed, 74 insertions, 0 deletions

diff --git a/docs/deprecated/zip_safe.rst b/docs/deprecated/zip_safe.rst
new file mode 100644
index 00000000..1b299b3c
--- /dev/null
+++ b/docs/deprecated/zip_safe.rst
@@ -0,0 +1,74 @@
+Understanding the ``zip_safe`` flag
+===================================
+
+The ``zip_safe`` flag is a ``setuptools`` configuration mainly associated
+with the ``egg`` distribution format
+(which got replaced in the ecosystem by the newer ``wheel`` format) and the
+``easy_install`` command (deprecated in ``setuptools`` v58.3.0).
+
+It is very unlikely that the values of ``zip_safe`` will affect modern
+deployments that use :pypi:`pip` for installing packages.
+Moreover, new users of ``setuptools`` should not attempt to create egg files
+using the deprecated ``build_egg`` command.
+Therefore, this flag is considered **obsolete**.
+
+This document, however, describes what was the historical motivation behind
+this flag, and how it was used.
+
+Historical Motivation
+---------------------
+
+For some use cases (such as bundling as part of a larger application), Python
+packages may be run directly from a zip file.
+Not all packages, however, are capable of running in compressed form, because
+they may expect to be able to access either source code or data files as
+normal operating system files.
+
+In the past, ``setuptools`` would install an project distributed
+as a zipfile or a directory (via the ``easy_install`` command or
+``python setup.py install``),
+the default choice being determined by the project's ``zip_safe`` flag.
+
+How the ``zip_safe`` flag was used?
+-----------------------------------
+
+To set this flag, a developer would pass a boolean value for the ``zip_safe`` argument to the
+``setup()`` function, or omit it.  When omitted, the ``bdist_egg``
+command would analyze the project's contents to see if it could detect any
+conditions that preventing the project from working in a zipfile.
+
+This was extremely conservative: ``bdist_egg`` would consider the
+project unsafe if it contained any C extensions or datafiles whatsoever.  This
+does *not* mean that the project couldn't or wouldn't work as a zipfile!  It just
+means that the ``bdist_egg`` authors were not yet comfortable asserting that
+the project *would* work.  If the project did not contain any C or data files, and did not
+attempt to perform ``__file__`` or ``__path__`` introspection or source code manipulation, then
+there was an extremely solid chance the project will work when installed as a
+zipfile.  (And if the project used ``pkg_resources`` for all its data file
+access, then C extensions and other data files shouldn't be a problem at all.
+See the :ref:`Accessing Data Files at Runtime` section for more information.)
+
+The developer could manually set ``zip_safe`` to ``True`` to perform tests,
+or to override the default behaviour (after checking all the warnings and
+understanding the implications), this would allow ``setuptools`` to install the
+project as a zip file. Alternatively, by setting ``zip_safe`` to ``False``,
+developers could force ``setuptools`` to always install the project as a
+directory.
+
+Modern ways of loading packages from zip files
+----------------------------------------------
+
+Currently, popular Python package installers (such as :pypi:`pip`) and package
+indexes (such as PyPI_) consider that distribution packages are always
+installed as a directory.
+It is however still possible to load packages from zip files added to
+:obj:`sys.path`, thanks to the :mod:`zipimport` module 
+and the :mod:`importlib` machinery provided by Python standard library.
+
+When working with modules loaded from a zip file, it is important to keep in
+mind that values of ``__file__`` and ``__path__`` might not work as expected.
+Please check the documentation for :mod:`importlib.resources`, if file
+locations are important for your use case.
+
+
+.. _PyPI: https://pypi.org