From 125adbed88190435f00eb82720ccd5d0c9e9f5b1 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 21 May 2024 16:13:18 -0400 Subject: [PATCH 1/4] Break up HOWTO contents into separate section --- Doc/howto/index.rst | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/Doc/howto/index.rst b/Doc/howto/index.rst index 065071e39a06c5..466b492ea713c4 100644 --- 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 @@ -35,3 +33,33 @@ Currently, the HOWTOs are: timerfd.rst mro.rst +General: + +* :ref:`Annotations Best Practices ` +* :ref:`Descriptor Guide ` +* :ref:`Enum HOWTO ` +* :ref:`Functional Programming HOWTO ` +* :ref:`An introduction to the ipaddress module ` +* :ref:`Logging HOWTO ` +* :ref:`Logging Cookbook ` +* :ref:`Regular Expression HOWTO ` +* :ref:`Sorting Techniques ` +* :ref:`Unicode HOWTO ` +* :ref:`HOWTO Fetch Internet Resources Using The urllib Package ` + +Advanced development: + +* :ref:`Curses Programming with Python `` +* :ref:`Socket Programming HOWTO ` +* :ref:`Isolating Extension Modules ` + +Debugging and profiling: + +* :ref:`Debugging C API extensions and CPython Internals with GDB ` +* :ref:`Instrumenting CPython with DTrace and SystemTap ` +* :ref:`Python support for the Linux perf profiler ` + +Python 2 and Migration to 3: + +* :ref:`Porting Extension Modules to Python 3 ` +* :ref:`The Python 2.3 Method Resolution Order ` From ef9638d3bc7831f9983b885fcdcd639beb49b36d Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 21 May 2024 17:23:30 -0400 Subject: [PATCH 2/4] Update the HOWTO index page to group documents into sections --- Doc/howto/enum.rst | 2 ++ Doc/howto/functional.rst | 2 ++ Doc/howto/index.rst | 36 +++++++++++++++++------------------- Doc/howto/logging.rst | 2 ++ 4 files changed, 23 insertions(+), 19 deletions(-) diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index 30be15230fc088..748ec5b24365d1 100644 --- 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 b0f9d22d74f0e3..1f0608fb0fc53f 100644 --- 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 466b492ea713c4..0c8c0af527d20c 100644 --- a/Doc/howto/index.rst +++ b/Doc/howto/index.rst @@ -35,31 +35,29 @@ Python Library Reference. General: -* :ref:`Annotations Best Practices ` -* :ref:`Descriptor Guide ` -* :ref:`Enum HOWTO ` -* :ref:`Functional Programming HOWTO ` -* :ref:`An introduction to the ipaddress module ` -* :ref:`Logging HOWTO ` +* :ref:`Annotations Best Practices ` +* :ref:`Argparse tutorial ` +* :ref:`Descriptor Guide ` +* :ref:`Enum HOWTO ` +* :ref:`Functional Programming HOWTO ` +* :ref:`An introduction to the ipaddress module ` +* :ref:`Logging HOWTO ` * :ref:`Logging Cookbook ` -* :ref:`Regular Expression HOWTO ` -* :ref:`Sorting Techniques ` -* :ref:`Unicode HOWTO ` -* :ref:`HOWTO Fetch Internet Resources Using The urllib Package ` +* :ref:`Regular Expression HOWTO ` +* :ref:`Sorting Techniques ` +* :ref:`Unicode HOWTO ` +* :ref:`HOWTO Fetch Internet Resources Using The urllib Package ` Advanced development: -* :ref:`Curses Programming with Python `` -* :ref:`Socket Programming HOWTO ` -* :ref:`Isolating Extension Modules ` +* :ref:`Curses Programming with Python ` +* :ref:`Isolating Extension Modules ` +* :ref:`The Python 2.3 Method Resolution Order ` +* :ref:`Socket Programming HOWTO ` +* :ref:`Timer file descriptor ` Debugging and profiling: -* :ref:`Debugging C API extensions and CPython Internals with GDB ` +* :ref:`Debugging C API extensions and CPython Internals with GDB ` * :ref:`Instrumenting CPython with DTrace and SystemTap ` * :ref:`Python support for the Linux perf profiler ` - -Python 2 and Migration to 3: - -* :ref:`Porting Extension Modules to Python 3 ` -* :ref:`The Python 2.3 Method Resolution Order ` diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index ab758a885b3556..cf5b693d8e3851 100644 --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -1,3 +1,5 @@ +.. _logging-howto: + ============= Logging HOWTO ============= From 74caa71961d775095e9943f8fb6b9a3adfe6158f Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Wed, 22 May 2024 09:39:22 -0400 Subject: [PATCH 3/4] Apply Ned's simplification Co-authored-by: Ned Batchelder --- Doc/howto/index.rst | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/Doc/howto/index.rst b/Doc/howto/index.rst index 0c8c0af527d20c..989690db42c611 100644 --- a/Doc/howto/index.rst +++ b/Doc/howto/index.rst @@ -35,29 +35,29 @@ Python Library Reference. General: -* :ref:`Annotations Best Practices ` -* :ref:`Argparse tutorial ` -* :ref:`Descriptor Guide ` -* :ref:`Enum HOWTO ` -* :ref:`Functional Programming HOWTO ` -* :ref:`An introduction to the ipaddress module ` -* :ref:`Logging HOWTO ` -* :ref:`Logging Cookbook ` -* :ref:`Regular Expression HOWTO ` -* :ref:`Sorting Techniques ` -* :ref:`Unicode HOWTO ` -* :ref:`HOWTO Fetch Internet Resources Using The urllib Package ` +* :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 Programming with Python ` -* :ref:`Isolating Extension Modules ` -* :ref:`The Python 2.3 Method Resolution Order ` -* :ref:`Socket Programming HOWTO ` -* :ref:`Timer file descriptor ` +* :ref:`curses-howto` +* :ref:`isolating-extensions-howto` +* :ref:`python_2.3_mro` +* :ref:`socket-howto` +* :ref:`timerfd-howto` Debugging and profiling: -* :ref:`Debugging C API extensions and CPython Internals with GDB ` -* :ref:`Instrumenting CPython with DTrace and SystemTap ` -* :ref:`Python support for the Linux perf profiler ` +* :ref:`gdb` +* :ref:`instrumentation` +* :ref:`perf_profiling` From d25ed7448475d5cc4d874793aad6ec2731dd8bb7 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 14 Jun 2024 12:51:17 +0200 Subject: [PATCH 4/4] Add cporting-howto back --- Doc/howto/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/howto/index.rst b/Doc/howto/index.rst index 989690db42c611..71880079f3ff0c 100644 --- a/Doc/howto/index.rst +++ b/Doc/howto/index.rst @@ -55,6 +55,7 @@ Advanced development: * :ref:`python_2.3_mro` * :ref:`socket-howto` * :ref:`timerfd-howto` +* :ref:`cporting-howto` Debugging and profiling: