Apply docs revamp

changelog.d/2097.doc.rst

@@ -0,0 +1 @@
+doc: simplify index and group deprecated files

changelog.d/2102.doc.rst

@@ -0,0 +1 @@
+doc overhaul step 2: break main doc into multiple sections

changelog.d/2111.doc.rst

@@ -0,0 +1 @@
+doc overhaul step 3: update userguide

docs/deprecated/functionalities.txt

@@ -0,0 +1,33 @@
+"Eggsecutable" Scripts
+----------------------
+
+.. deprecated:: 45.3.0
+
+Occasionally, there are situations where it's desirable to make an ``.egg``
+file directly executable.  You can do this by including an entry point such
+as the following::
+
+    setup(
+        # other arguments here...
+        entry_points={
+            "setuptools.installation": [
+                "eggsecutable = my_package.some_module:main_func",
+            ]
+        }
+    )
+
+Any eggs built from the above setup script will include a short executable
+prelude that imports and calls ``main_func()`` from ``my_package.some_module``.
+The prelude can be run on Unix-like platforms (including Mac and Linux) by
+invoking the egg with ``/bin/sh``, or by enabling execute permissions on the
+``.egg`` file.  For the executable prelude to run, the appropriate version of
+Python must be available via the ``PATH`` environment variable, under its
+"long" name.  That is, if the egg is built for Python 2.3, there must be a
+``python2.3`` executable present in a directory on ``PATH``.
+
+IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or
+invoked via symlinks.  They *must* be invoked using their original filename, in
+order to ensure that, once running, ``pkg_resources`` will know what project
+and version is in use.  The header script will check this and exit with an
+error if the ``.egg`` file has been renamed or is invoked via a symlink that
+changes its base name.

docs/deprecated/index.txt

@@ -0,0 +1,19 @@
+======================================================
+Guides on backward compatibility & deprecated practice
+======================================================
+
+``Setuptools`` has undergone tremendous changes since its first debut. As its
+development continues to roll forward, many of the practice and mechanisms it
+had established are now considered deprecated. But they still remain relevant
+as a plethora of libraries continue to depend on them. Many people also find
+it necessary to equip themselves with the knowledge to better support backward
+compatibility. This guide aims to provide the essential information for such
+objectives.
+
+.. toctree::
+    :maxdepth: 1
+
+    python3
+    python_eggs
+    easy_install
+    distutils-legacy

docs/index.txt

@@ -7,13 +7,8 @@ designed to facilitate packaging Python projects.
 Documentation content:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   setuptools
-   pkg_resources
-   python3
-   development
-   roadmap
-   Deprecated: Easy Install <easy_install>
-   distutils-legacy
-   history
+   User guide <userguide/index>
+   Development guide <development>
+   Backward compatibility & deprecated practice <deprecated/index>