[3.13] Update the documentation howto index page and group docs into 3 logical sectio...

Update the documentation howto index page and group docs into 3 logical sections (GH-119366)

(cherry picked from commit a26d27e7ee512cd822b7a7ba075171152779ffdd)

Includes a follow-up fix to properly merge GH-119877:
* Add a link to free-threading HOWTO to the index (GH-120703)
  (cherry picked from commit 45d5cab533a607716b2b41134839a59facf309cd)

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>

diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
index 0b122ae72b075d505b493d8598b1c4583a373eaa..18e13fcf9f59bd925e077ca74b0295330af6af00 100644 (file)
--- a/Doc/howto/enum.rst
+++ b/Doc/howto/enum.rst
@@ -1,3 +1,5 @@
+.. _enum-howto:
+
 ==========
 Enum HOWTO
 ==========

diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
index b0f9d22d74f0e3111f3632504394772f404f0ce4..1f0608fb0fc53f02fd8c267f3ca87c14c3a7a803 100644 (file)
--- a/Doc/howto/functional.rst
+++ b/Doc/howto/functional.rst
@@ -1,3 +1,5 @@
+.. _functional-howto:
+
 ********************************
   Functional Programming HOWTO
 ********************************

diff --git a/Doc/howto/index.rst b/Doc/howto/index.rst
index a1f17eca906291824d3a1106149138e7530c4219..a882f1747084fedf47e22261403ad5559aece781 100644 (file)
--- a/Doc/howto/index.rst
+++ b/Doc/howto/index.rst
@@ -2,16 +2,14 @@
  Python HOWTOs
 ***************
 
-Python HOWTOs are documents that cover a single, specific topic,
-and attempt to cover it fairly completely. Modelled on the Linux
-Documentation Project's HOWTO collection, this collection is an
+Python HOWTOs are documents that cover a specific topic in-depth.
+Modeled on the Linux Documentation Project's HOWTO collection, this collection is an
 effort to foster documentation that's more detailed than the
 Python Library Reference.
 
-Currently, the HOWTOs are:
-
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    cporting.rst
    curses.rst
@@ -36,3 +34,33 @@ Currently, the HOWTOs are:
    mro.rst
    free-threading-extensions.rst
 
+General:
+
+* :ref:`annotations-howto`
+* :ref:`argparse-tutorial`
+* :ref:`descriptorhowto`
+* :ref:`enum-howto`
+* :ref:`functional-howto`
+* :ref:`ipaddress-howto`
+* :ref:`logging-howto`
+* :ref:`logging-cookbook`
+* :ref:`regex-howto`
+* :ref:`sortinghowto`
+* :ref:`unicode-howto`
+* :ref:`urllib-howto`
+
+Advanced development:
+
+* :ref:`curses-howto`
+* :ref:`freethreading-extensions-howto`
+* :ref:`isolating-extensions-howto`
+* :ref:`python_2.3_mro`
+* :ref:`socket-howto`
+* :ref:`timerfd-howto`
+* :ref:`cporting-howto`
+
+Debugging and profiling:
+
+* :ref:`gdb`
+* :ref:`instrumentation`
+* :ref:`perf_profiling`

diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index ab758a885b355643cd925265a74fed7949b67f1d..cf5b693d8e38514abbc165f7c9fa1ebe5cc24708 100644 (file)
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -1,3 +1,5 @@
+.. _logging-howto:
+
 =============
 Logging HOWTO
 =============