Add a table of contents to DIRECTORY.md

Generate a linked table of contents of the top-level sections at the top
of DIRECTORY.md so readers can jump straight to a category, as suggested
in #13239 / #13111. The list is built in scripts/build_directory_md.py
(with a new md_anchor helper + doctests) so DIRECTORY.md stays fully
auto-generated.

Author: priya-sundaram-dev

DIRECTORY.md

@@ -1,3 +1,49 @@
+## Table of Contents
+* [Audio Filters](#audio-filters)
+* [Backtracking](#backtracking)
+* [Bit Manipulation](#bit-manipulation)
+* [Blockchain](#blockchain)
+* [Boolean Algebra](#boolean-algebra)
+* [Cellular Automata](#cellular-automata)
+* [Ciphers](#ciphers)
+* [Computer Vision](#computer-vision)
+* [Conversions](#conversions)
+* [Data Compression](#data-compression)
+* [Data Structures](#data-structures)
+* [Digital Image Processing](#digital-image-processing)
+* [Divide And Conquer](#divide-and-conquer)
+* [Docs](#docs)
+* [Dynamic Programming](#dynamic-programming)
+* [Electronics](#electronics)
+* [File Transfer](#file-transfer)
+* [Financial](#financial)
+* [Fractals](#fractals)
+* [Fuzzy Logic](#fuzzy-logic)
+* [Genetic Algorithm](#genetic-algorithm)
+* [Geodesy](#geodesy)
+* [Geometry](#geometry)
+* [Graphics](#graphics)
+* [Graphs](#graphs)
+* [Greedy Methods](#greedy-methods)
+* [Hashes](#hashes)
+* [Knapsack](#knapsack)
+* [Linear Algebra](#linear-algebra)
+* [Linear Programming](#linear-programming)
+* [Machine Learning](#machine-learning)
+* [Maths](#maths)
+* [Matrix](#matrix)
+* [Networking Flow](#networking-flow)
+* [Neural Network](#neural-network)
+* [Other](#other)
+* [Physics](#physics)
+* [Project Euler](#project-euler)
+* [Quantum](#quantum)
+* [Scheduling](#scheduling)
+* [Searches](#searches)
+* [Sorts](#sorts)
+* [Strings](#strings)
+* [Tests](#tests)
+* [Web Programming](#web-programming)
 
 ## Audio Filters
   * [Butterworth Filter](audio_filters/butterworth_filter.py)

scripts/build_directory_md.py

@@ -34,6 +34,21 @@ def md_prefix(indent: int) -> str:
     return f"{indent * '  '}*" if indent else "\n##"
 
 
+def md_anchor(heading: str) -> str:
+    """
+    GitHub-style anchor slug for a section heading, so the table of contents
+    can link to it.
+
+    >>> md_anchor("Audio Filters")
+    'audio-filters'
+    >>> md_anchor("Bit Manipulation")
+    'bit-manipulation'
+    >>> md_anchor("Computer Vision")
+    'computer-vision'
+    """
+    return heading.strip().lower().replace(" ", "-")
+
+
 def print_path(old_path: str, new_path: str) -> str:
     old_parts = old_path.split(os.sep)
     for i, new_part in enumerate(new_path.split(os.sep)):
@@ -43,8 +58,22 @@ def print_path(old_path: str, new_path: str) -> str:
 
 
 def print_directory_md(top_dir: str = ".") -> None:
+    filepaths = sorted(good_file_paths(top_dir))
+
+    # Top-level sections, in the order they appear, for the table of contents.
+    sections = list(
+        dict.fromkeys(
+            fp.split(os.sep)[0].replace("_", " ").title()
+            for fp in filepaths
+            if os.sep in fp
+        )
+    )
+    print("## Table of Contents")
+    for section in sections:
+        print(f"* [{section}](#{md_anchor(section)})")
+
     old_path = ""
-    for filepath in sorted(good_file_paths(top_dir)):
+    for filepath in filepaths:
         filepath, filename = os.path.split(filepath)
         if filepath != old_path:
             old_path = print_path(old_path, filepath)